@xnoxs/flux-lang 3.3.4 → 3.4.1

package/src/self/cli.flux

@@ -0,0 +1,996 @@
+// ============================================================
+//  Flux Self-Hosted CLI  — flux command line interface
+//  src/self/cli.flux — written in Flux, compiled by stage-0
+//
+//  Self-hosted: this CLI is compiled by the Flux compiler itself.
+//  Run via: node bin/flux.js run src/self/cli.flux
+//  Or after bootstrap: FLUX_SELF_HOSTED=1 flux <command>
+// ============================================================
+
+import Fs   from "fs"
+import Path from "path"
+import Os   from "os"
+import { transpile, FLUX_VERSION, FLUX_STAGE } from "./transpiler"
+import { bundle }                               from "./bundler"
+import { format }                               from "./formatter"
+import { lint }                                 from "./linter"
+import { runTests }                             from "./test-runner"
+import { loadConfig }                           from "./config"
+import {
+  cmdAdd, cmdRemove, cmdInstall, cmdList,
+  cmdSearch, cmdInfo, cmdPublish
+} from "./pkg"
+
+// ── Version ───────────────────────────────────────────────────
+val VERSION = FLUX_VERSION ?? "3.0.0"
+val STAGE   = FLUX_STAGE   ?? "self-hosted"
+
+// ── ANSI Colors ───────────────────────────────────────────────
+val C = {
+  reset:   "\x1b[0m",
+  bold:    "\x1b[1m",
+  dim:     "\x1b[2m",
+  red:     "\x1b[31m",
+  green:   "\x1b[32m",
+  yellow:  "\x1b[33m",
+  blue:    "\x1b[34m",
+  cyan:    "\x1b[36m",
+  white:   "\x1b[37m",
+  gray:    "\x1b[90m",
+  magenta: "\x1b[35m",
+}
+
+val noColor = process.env.NO_COLOR or not process.stdout.isTTY
+fn clr(c, s): return noColor ? s : c + s + C.reset
+fn bold(s):   return clr(C.bold, s)
+fn gray(s):   return clr(C.gray, s)
+fn green(s):  return clr(C.green, s)
+fn red(s):    return clr(C.red, s)
+fn cyan(s):   return clr(C.cyan, s)
+fn yellow(s): return clr(C.yellow, s)
+fn blue(s):   return clr(C.blue, s)
+
+// ── Banner ────────────────────────────────────────────────────
+fn showBanner():
+  if noColor:
+    console.log("Flux Lang " + VERSION + " [" + STAGE + "]")
+    return
+  console.log(cyan(bold(`
+  ███████╗██╗     ██╗   ██╗██╗  ██╗
+  ██╔════╝██║     ██║   ██║╚██╗██╔╝
+  █████╗  ██║     ██║   ██║ ╚███╔╝
+  ██╔══╝  ██║     ██║   ██║ ██╔██╗
+  ██║     ███████╗╚██████╔╝██╔╝ ██╗
+  ╚═╝     ╚══════╝ ╚═════╝ ╚═╝  ╚═╝`)))
+  console.log(gray("  Flux Lang v" + VERSION + "  [" + STAGE + "]  → JavaScript\n"))
+
+// ── Help ──────────────────────────────────────────────────────
+fn showHelp():
+  showBanner()
+  console.log(bold("USAGE:"))
+  console.log("  flux <command> [options]\n")
+
+  console.log(bold("COMPILER:"))
+  val compilerCmds = [
+    ["compile <file.flux>",            "Compile .flux → .js"],
+    ["bundle  <entry.flux>",           "Bundle multiple files into one .js"],
+    ["run     <file.flux>",            "Compile and run immediately"],
+    ["watch   <file.flux>",            "Watch for changes, auto-compile"],
+    ["check   <file.flux>",            "Type-check and static analysis"],
+  ]
+  for [cmd, desc] in compilerCmds:
+    console.log("  " + green(("flux " + cmd).padEnd(36)) + " " + gray(desc))
+
+  console.log()
+  console.log(bold("TOOLING:"))
+  val toolCmds = [
+    ["lint    <file.flux>",            "Full lint: types + style + immutability"],
+    ["fmt     <file.flux>",            "Format source code in-place"],
+    ["test    [dir]",                  "Run *.test.flux files"],
+    ["repl",                           "Interactive REPL mode"],
+    ["tokens  <file.flux>",            "Show lexer token list"],
+    ["ast     <file.flux>",            "Show Abstract Syntax Tree (JSON)"],
+  ]
+  for [cmd, desc] in toolCmds:
+    console.log("  " + green(("flux " + cmd).padEnd(36)) + " " + gray(desc))
+
+  console.log()
+  console.log(bold("PACKAGE MANAGER:"))
+  val pkgCmds = [
+    ["init    [name]",                 "Scaffold a new Flux project"],
+    ["add     <pkg[@version]>",        "Add a dependency"],
+    ["remove  <pkg>",                  "Remove a dependency"],
+    ["install",                        "Install all dependencies"],
+    ["list",                           "List installed packages"],
+    ["search  <query>",                "Search the package registry"],
+    ["info    <pkg>",                  "Show package details"],
+    ["publish",                        "Publish package to registry"],
+  ]
+  for [cmd, desc] in pkgCmds:
+    console.log("  " + cyan(("flux " + cmd).padEnd(36)) + " " + gray(desc))
+
+  console.log()
+  console.log(bold("SELF-HOSTED:"))
+  val selfCmds = [
+    ["self-hosted",                    "Show self-hosted compiler status"],
+    ["self-hosted build",              "Bootstrap: compile compiler with itself"],
+    ["self-hosted verify",             "Verify self-hosted output matches stage-0"],
+  ]
+  for [cmd, desc] in selfCmds:
+    console.log("  " + yellow(("flux " + cmd).padEnd(36)) + " " + gray(desc))
+
+  console.log()
+  console.log(bold("OPTIONS:"))
+  console.log("  " + yellow("--out, -o <file>  ") + "  Output file")
+  console.log("  " + yellow("--sourcemap, -m   ") + "  Generate .js.map")
+  console.log("  " + yellow("--watch, -w       ") + "  Watch mode")
+  console.log("  " + yellow("--mangle          ") + "  Minify identifiers")
+  console.log("  " + yellow("--typecheck       ") + "  Enable type checking")
+  console.log("  " + yellow("--stdout          ") + "  Print to terminal")
+  console.log("  " + yellow("--no-color        ") + "  Disable colors")
+  console.log()
+
+// ── Parse CLI args ────────────────────────────────────────────
+fn parseArgs(argv):
+  val args  = argv.slice(2)
+  val opts  = {
+    out:       null,
+    sourcemap: false,
+    mangle:    false,
+    typecheck: false,
+    strict:    false,
+    stdout:    false,
+    watch:     false,
+    dev:       false,
+    verbose:   false,
+    jsx:       false,
+    jsxTarget: "browser",
+  }
+  val positional = []
+  var i = 0
+  while i < args.length:
+    val a = args[i]
+    if a == "--out" or a == "-o":
+      i = i + 1
+      opts.out = args[i]
+    else if a == "--sourcemap" or a == "-m":
+      opts.sourcemap = true
+    else if a == "--mangle":
+      opts.mangle = true
+    else if a == "--typecheck" or a == "-t":
+      opts.typecheck = true
+    else if a == "--strict":
+      opts.strict = true
+    else if a == "--stdout":
+      opts.stdout = true
+    else if a == "--watch" or a == "-w":
+      opts.watch = true
+    else if a == "--dev":
+      opts.dev = true
+    else if a == "--verbose" or a == "-v":
+      opts.verbose = true
+    else if a == "--jsx":
+      opts.jsx = true
+    else if a == "--jsx-target":
+      i = i + 1
+      opts.jsxTarget = args[i]
+    else if not a.startsWith("--"):
+      positional.push(a)
+    i = i + 1
+  return { positional, opts }
+
+// ── Read file or exit ─────────────────────────────────────────
+fn readFluxFile(filePath):
+  val abs = Path.resolve(filePath)
+  if not Fs.existsSync(abs):
+    console.error(red("✗ File not found: " + abs))
+    process.exit(1)
+  if not filePath.endsWith(".flux"):
+    console.warn(yellow("⚠  Not a .flux file: " + filePath))
+  return { source: Fs.readFileSync(abs, "utf8"), abs }
+
+// ── Derive output path ────────────────────────────────────────
+fn deriveOutPath(inputPath, outFlag):
+  if outFlag: return Path.resolve(outFlag)
+  val base = Path.basename(inputPath, ".flux")
+  return Path.join(Path.dirname(Path.resolve(inputPath)), base + ".js")
+
+// ── Error renderer ────────────────────────────────────────────
+val ERROR_KIND = {
+  ParseError:     "Syntax error",
+  LexerError:     "Syntax error",
+  CheckError:     "Static error",
+  TypeCheckError: "Type error",
+  TypeError:      "Type error",
+}
+
+fn printErrors(errors, source, filePath):
+  val lines = source.split("\n")
+  for err in errors:
+    val kind  = ERROR_KIND[err.name] ?? "Error"
+    val stage = err.stage ? gray(" [" + err.stage + "]") : ""
+    console.error()
+    console.error(red(bold(kind)) + stage)
+    if err.line:
+      val fileLabel = filePath ? cyan(Path.relative(process.cwd(), filePath)) : ""
+      val locLabel  = yellow(err.line + ":" + (err.col ?? 1))
+      if fileLabel: console.error("  " + fileLabel + ":" + locLabel)
+      else:         console.error("  Line " + locLabel)
+    console.error("  " + err.message)
+    if err.line and err.line <= lines.length:
+      val errLineIdx = err.line - 1
+      val col        = Math.max(0, (err.col ?? 1) - 1)
+      val tokLen     = Math.max(1, err.len ?? 1)
+      if errLineIdx > 0 and lines[errLineIdx - 1].trim() != "":
+        val prev = String(err.line - 1).padStart(4)
+        console.error(gray("  " + prev + " │ " + lines[errLineIdx - 1]))
+      val lineNum  = String(err.line).padStart(4)
+      console.error(gray("  " + lineNum + " │ ") + lines[errLineIdx])
+      val squiggle = "^" + "~".repeat(Math.max(0, tokLen - 1))
+      val pointer  = " ".repeat(col) + red(squiggle)
+      console.error(gray("       │ ") + pointer)
+      if errLineIdx + 1 < lines.length and lines[errLineIdx + 1].trim() != "":
+        val next = String(err.line + 1).padStart(4)
+        console.error(gray("  " + next + " │ " + lines[errLineIdx + 1]))
+    if err.hint:
+      console.error(cyan("  Hint: ") + gray(err.hint))
+  console.error()
+
+// ══════════════════════════════════════════════════════════════
+//  Commands
+// ══════════════════════════════════════════════════════════════
+
+// ── flux compile ──────────────────────────────────────────────
+fn cmdCompile(filePath, opts):
+  val { source, abs } = readFluxFile(filePath)
+  val cfg     = loadConfig(Path.dirname(abs))
+  val outPath = deriveOutPath(filePath, opts.out)
+  val mapPath = outPath + ".map"
+  val t0      = Date.now()
+
+  val result = transpile(source, {
+    sourcemap:  opts.sourcemap ?? cfg.sourcemap,
+    mangle:     opts.mangle    ?? cfg.mangle,
+    typecheck:  opts.typecheck ?? cfg.typecheck,
+    jsx:        opts.jsx       ?? cfg.jsx,
+    jsxTarget:  opts.jsxTarget ?? cfg.jsxTarget,
+    sourceFile: Path.relative(Path.dirname(outPath), abs),
+    outputFile: Path.basename(outPath),
+  })
+
+  if not result.success:
+    console.error(red("\n✗ Compile failed — " + result.errors.length + " error(s)"))
+    printErrors(result.errors, source, abs)
+    process.exit(1)
+
+  val elapsed = Date.now() - t0
+
+  if opts.stdout:
+    console.log(result.output)
+    return
+
+  Fs.writeFileSync(outPath, result.output, "utf8")
+
+  var extra = ""
+  if opts.sourcemap and result.sourceMap:
+    Fs.writeFileSync(mapPath, result.sourceMap, "utf8")
+    extra = gray(" + " + Path.relative(process.cwd(), mapPath))
+
+  val rel  = Path.relative(process.cwd(), abs)
+  val relO = Path.relative(process.cwd(), outPath)
+  console.log(
+    green("✓ ") + gray("(" + elapsed + "ms) ") +
+    blue(rel) + gray(" → ") + cyan(relO) + extra
+  )
+
+  if result.typeErrors and result.typeErrors.length > 0:
+    console.warn(yellow("\n⚠  " + result.typeErrors.length + " type warning(s)"))
+    printErrors(result.typeErrors, source, abs)
+
+// ── flux run ──────────────────────────────────────────────────
+fn cmdRun(filePath, opts):
+  val { source, abs } = readFluxFile(filePath)
+  val result = transpile(source, {
+    jsx:       opts.jsx       ?? false,
+    jsxTarget: opts.jsxTarget ?? "browser",
+    mangle:    false,
+  })
+
+  if not result.success:
+    console.error(red("\n✗ Compile error"))
+    printErrors(result.errors, source, abs)
+    process.exit(1)
+
+  val tmpPath = Path.join(Os.tmpdir(), "_flux_run_" + Date.now() + ".js")
+  Fs.writeFileSync(tmpPath, result.output, "utf8")
+  console.log(gray("▶ Running " + Path.basename(abs) + " ...\n"))
+  try:
+    require(tmpPath)
+  catch(e):
+    console.error(red("\n[Runtime Error] " + e.message))
+    process.exitCode = 1
+  finally:
+    try: Fs.unlinkSync(tmpPath)
+    catch(e2): null
+
+// ── flux check ───────────────────────────────────────────────
+fn runCheck(abs):
+  val source   = Fs.readFileSync(abs, "utf8")
+  val baseName = Path.basename(abs)
+  val result   = transpile(source, { check: true, typecheck: true })
+
+  if not result.success:
+    val n    = result.errors.length
+    val kind = result.errors.some(e -> e.name == "CheckError") ? "static" : "syntax"
+    console.error(red("\n✗ " + baseName + ": " + n + " " + kind + " error(s)"))
+    printErrors(result.errors, source, abs)
+    return { ok: false, typeErrors: 0, warnings: 0 }
+
+  var allOk = true
+  val typeErrors = result.typeErrors ?? []
+  if typeErrors.length > 0:
+    console.error(red("\n✗ " + baseName + ": " + typeErrors.length + " type error(s)"))
+    printErrors(typeErrors, source, abs)
+    allOk = false
+
+  val warnings = result.typeWarnings ?? []
+  for w in warnings:
+    val fileRef = cyan(baseName) + (w.line ? yellow(":" + w.line) : "")
+    console.warn(yellow("  ⚠ ") + fileRef + gray("  " + w.message))
+    if w.hint: console.warn(cyan("    Hint: ") + gray(w.hint))
+
+  val fnRe  = /^(?:async )?function \w/gm
+  val clsRe = /^class \w/gm
+  val fns   = (result.output.match(fnRe)  ?? []).length
+  val cls   = (result.output.match(clsRe) ?? []).length
+
+  if allOk:
+    console.log(
+      green("✓ ") + cyan(baseName) + gray(" — no errors") +
+      gray("  Functions: " + fns + "  |  Classes: " + cls + "  |  JS output: " + result.output.split("\n").length + " lines")
+    )
+
+  return { ok: allOk, typeErrors: typeErrors.length, warnings: warnings.length }
+
+fn cmdCheck(filePaths, opts):
+  if filePaths.length == 0:
+    console.error(red("✗ No files specified"))
+    process.exit(1)
+
+  var totalErrors   = 0
+  var totalWarnings = 0
+
+  for filePath in filePaths:
+    val abs = Path.resolve(filePath)
+    if not Fs.existsSync(abs):
+      console.error(red("✗ File not found: " + filePath))
+      totalErrors = totalErrors + 1
+      continue
+    val r = runCheck(abs)
+    if not r.ok: totalErrors = totalErrors + 1
+    totalWarnings = totalWarnings + r.warnings
+
+  console.log()
+  if totalErrors > 0:
+    console.error(red("✗ " + totalErrors + " file(s) with errors"))
+    process.exit(1)
+  else:
+    console.log(green("✓ All files OK") + (totalWarnings > 0 ? yellow("  (" + totalWarnings + " warning(s))") : ""))
+
+// ── flux fmt ──────────────────────────────────────────────────
+fn cmdFmt(filePaths, opts):
+  var changed = 0
+  for filePath in filePaths:
+    val abs = Path.resolve(filePath)
+    if not Fs.existsSync(abs):
+      console.error(red("✗ Not found: " + filePath))
+      continue
+    val source    = Fs.readFileSync(abs, "utf8")
+    val formatted = format(source)
+    if formatted != source:
+      if not opts.stdout:
+        Fs.writeFileSync(abs, formatted, "utf8")
+        console.log(green("✓ ") + gray("Formatted ") + cyan(Path.relative(process.cwd(), abs)))
+        changed = changed + 1
+      else:
+        console.log(formatted)
+    else:
+      console.log(gray("○ ") + gray("No changes: ") + Path.relative(process.cwd(), abs))
+
+  if not opts.stdout and changed > 0:
+    console.log()
+    console.log(green("✓ " + changed + " file(s) formatted"))
+
+// ── flux lint ─────────────────────────────────────────────────
+fn cmdLint(filePaths, opts):
+  var hasErrors = false
+  for filePath in filePaths:
+    val abs = Path.resolve(filePath)
+    if not Fs.existsSync(abs):
+      console.error(red("✗ Not found: " + filePath))
+      continue
+    val source = Fs.readFileSync(abs, "utf8")
+    val result = lint(source)
+    val name   = Path.relative(process.cwd(), abs)
+
+    if result.errors.length == 0 and result.warnings.length == 0:
+      console.log(green("✓ ") + cyan(name) + gray("  —  clean"))
+    else:
+      for e in result.errors:
+        console.error(red("  error ") + cyan(name + ":" + (e.line ?? "?")) + "  " + e.message)
+        hasErrors = true
+      for w in result.warnings:
+        console.warn(yellow("  warn  ") + cyan(name + ":" + (w.line ?? "?")) + "  " + w.message)
+
+  if hasErrors: process.exit(1)
+
+// ── flux bundle ───────────────────────────────────────────────
+fn cmdBundle(entryPath, opts):
+  val abs = Path.resolve(entryPath)
+  if not Fs.existsSync(abs):
+    console.error(red("✗ File not found: " + entryPath))
+    process.exit(1)
+
+  val outFile = opts.out ?? Path.join(Path.dirname(abs), Path.basename(abs, ".flux") + ".bundle.js")
+  val t0      = Date.now()
+  val result  = bundle(abs)
+
+  if not result.success:
+    console.error(red("\n✗ Bundle failed:\n"))
+    for e in result.errors:
+      console.error(red("  " + e.message))
+    process.exit(1)
+
+  val elapsed = Date.now() - t0
+  if opts.stdout:
+    console.log(result.code)
+    return
+
+  Fs.writeFileSync(outFile, result.code, "utf8")
+  val kb = (result.code.length / 1024).toFixed(1)
+  console.log(
+    green("✓ Bundle done") + gray(" (" + elapsed + "ms) ") +
+    Path.basename(abs) + gray(" + " + (result.modules - 1) + " module(s) → ") +
+    cyan(Path.relative(process.cwd(), outFile)) + gray(" [" + kb + " KB]")
+  )
+
+// ── flux watch ───────────────────────────────────────────────
+fn cmdWatch(filePath, opts):
+  val abs = Path.resolve(filePath)
+  if not Fs.existsSync(abs):
+    console.error(red("✗ File not found: " + filePath))
+    process.exit(1)
+
+  console.log(cyan("◉ Watching ") + Path.relative(process.cwd(), abs) + gray(" (Ctrl+C to stop)\n"))
+  cmdCompile(filePath, opts)
+
+  var timer = null
+  fn onDebounce():
+    console.log(gray("\n" + new Date().toLocaleTimeString() + " — ") + blue("change detected"))
+    cmdCompile(filePath, opts)
+  fn onChange():
+    if timer: clearTimeout(timer)
+    timer = setTimeout(onDebounce, 80)
+  Fs.watch(abs, onChange)
+
+// ── flux tokens ───────────────────────────────────────────────
+fn cmdTokens(filePath, opts):
+  val { source } = readFluxFile(filePath)
+  val { Lexer }  = require(Path.join(__dirname, "lexer.js"))
+  val lexer      = new Lexer(source)
+  val tokens     = lexer.tokenize()
+  console.log(gray("Tokens (" + tokens.length + "):\n"))
+  for tok in tokens:
+    val loc = tok.line ? gray(" " + tok.line + ":" + (tok.col ?? 1)) : ""
+    val val_ = tok.value != null ? cyan("  " + JSON.stringify(tok.value)) : ""
+    console.log("  " + yellow(tok.type.padEnd(16)) + val_ + loc)
+
+// ── flux ast ──────────────────────────────────────────────────
+fn cmdAst(filePath, opts):
+  val { source } = readFluxFile(filePath)
+  val result     = transpile(source, {})
+  if not result.success:
+    printErrors(result.errors, source, filePath)
+    process.exit(1)
+  console.log(JSON.stringify(result.ast, null, 2))
+
+// ── flux repl ─────────────────────────────────────────────────
+fn cmdRepl(opts):
+  val readline = require("readline")
+  val rl = readline.createInterface({
+    input:    process.stdin,
+    output:   process.stdout,
+    terminal: true,
+    prompt:   cyan("flux") + gray("> "),
+  })
+
+  console.log()
+  console.log(bold("Flux Lang Interactive REPL") + gray("  v" + VERSION + "  [" + STAGE + "]"))
+  console.log(gray("Type Flux code to compile and run it. Ctrl+C or .exit to quit.\n"))
+  rl.prompt()
+
+  var multiLine = ""
+  var inBlock   = false
+
+  fn onLine(rawLine):
+    val line = rawLine
+
+    if line.trim() == ".exit" or line.trim() == ".quit":
+      console.log(gray("\nBye!"))
+      process.exit(0)
+
+    if line.trim() == ".help":
+      console.log(gray("  .exit  — quit"))
+      console.log(gray("  .clear — clear screen"))
+      console.log(gray("  .help  — this message"))
+      rl.prompt()
+      return
+
+    if line.trim() == ".clear":
+      console.clear()
+      rl.prompt()
+      return
+
+    val needsContinue = line.trimEnd().endsWith(":") or inBlock
+
+    if needsContinue and line.trim() != "":
+      multiLine = multiLine + line + "\n"
+      inBlock   = true
+      process.stdout.write(gray("... "))
+      return
+
+    val src = inBlock ? multiLine : line
+    multiLine = ""
+    inBlock   = false
+
+    if not src.trim():
+      rl.prompt()
+      return
+
+    try:
+      val result = transpile(src, { check: false })
+      if result.success:
+        val tmpPath = Path.join(Os.tmpdir(), "_flux_repl_" + Date.now() + ".js")
+        Fs.writeFileSync(tmpPath, result.output, "utf8")
+        try:
+          val out = require(tmpPath)
+          if out != undefined: console.log(green("← ") + JSON.stringify(out))
+        catch(e):
+          console.error(red("Runtime: ") + e.message)
+        finally:
+          try: Fs.unlinkSync(tmpPath)
+          catch(e2): null
+      else:
+        for e in result.errors:
+          console.error(red("✗ ") + e.message)
+    catch(e3):
+      console.error(red("Error: ") + e3.message)
+
+    rl.prompt()
+
+  fn onClose():
+    console.log(gray("\nBye!"))
+    process.exit(0)
+
+  rl.on("line", onLine)
+  rl.on("close", onClose)
+
+// ── flux init ────────────────────────────────────────────────
+fn cmdInit(name, opts):
+  val projectName = name ?? "my-flux-app"
+  val dir = Path.resolve(projectName)
+
+  if Fs.existsSync(dir):
+    console.error(red("✗ Directory already exists: " + projectName))
+    process.exit(1)
+
+  Fs.mkdirSync(dir, { recursive: true })
+  Fs.mkdirSync(Path.join(dir, "src"), { recursive: true })
+  Fs.mkdirSync(Path.join(dir, "tests"), { recursive: true })
+
+  val mainFlux = `// {projectName} — built with Flux Lang v{VERSION}
+// Run: flux run src/main.flux
+
+// ── Algebraic Data Types + Pattern Matching ───────────────────
+type Shape = Circle(radius) | Rect(width, height) | Triangle(base, height)
+
+fn area(shape):
+  match shape:
+    when Circle(r):      return Math.PI * r * r
+    when Rect(w, h):     return w * h
+    when Triangle(b, h): return 0.5 * b * h
+
+fn describe(shape):
+  match shape:
+    when Circle(r):      return "Circle(r={r:.2f})"
+    when Rect(w, h):     return "Rect({w:.1f}x{h:.1f})"
+    when Triangle(b, h): return "Triangle(b={b:.1f}, h={h:.1f})"
+
+// ── Result type ───────────────────────────────────────────────
+type Result = Ok(value) | Err(message)
+
+fn safeDivide(a, b):
+  if b == 0: return Err("division by zero")
+  return Ok(a / b)
+
+// ── Utility functions ─────────────────────────────────────────
+fn greet(name): return "Hello from Flux, {name}!"
+
+fn formatList(items):
+  if items.length == 0: return "(empty)"
+  return "[" + items.join(", ") + "]"
+
+fn clamp(value, lo, hi):
+  if value < lo: return lo
+  if value > hi: return hi
+  return value
+
+// ── Pipe operator + stdlib ────────────────────────────────────
+val numbers = [3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5]
+val processed = numbers
+  |> filter(n -> n > 3)
+  |> map(n -> n * n)
+  |> sort
+
+// ── Main ──────────────────────────────────────────────────────
+print(greet("{projectName}"))
+print("Squares > 3: {formatList(processed)}")
+print("clamp(12, 0, 10) = {clamp(12, 0, 10)}")
+
+val shapes = [Circle(5.0), Rect(8.0, 3.0), Triangle(6.0, 4.0)]
+for shape in shapes:
+  val a = area(shape)
+  print("{describe(shape)}  area={a:.2f}")
+
+match safeDivide(10.0, 3.0):
+  when Ok(v):  print("10 / 3 = {v:.4f}")
+  when Err(e): print("Error: {e}")
+`
+
+  val utilsFlux = `// Utility functions for {projectName}
+// Use with: flux bundle src/main.flux (bundles imports automatically)
+
+export fn greet(name):
+  return "Hello from Flux, {name}!"
+
+export fn formatList(items):
+  if items.length == 0: return "(empty)"
+  return "[" + items.join(", ") + "]"
+
+export fn clamp(value, lo, hi):
+  if value < lo: return lo
+  if value > hi: return hi
+  return value
+
+export fn sum(nums):
+  return nums.reduce((acc, x) -> acc + x, 0)
+
+export fn average(nums):
+  if nums.length == 0: return 0
+  return sum(nums) / nums.length
+`
+
+  val testFlux = `// Tests for {projectName}
+// Run: flux test tests/
+
+// ── Functions under test ──────────────────────────────────────
+fn add(a, b):
+    return a + b
+
+fn mul(a, b):
+    return a * b
+
+fn clamp(value, lo, hi):
+    if value < lo: return lo
+    if value > hi: return hi
+    return value
+
+fn average(nums):
+    if nums.length == 0: return 0
+    return nums.reduce((s, x) -> s + x, 0) / nums.length
+
+type Result = Ok(value) | Err(message)
+
+fn safeDivide(a, b):
+    if b == 0: return Err("div by zero")
+    return Ok(a / b)
+
+// ── Test functions ────────────────────────────────────────────
+fn test_add():
+    assert(add(1, 2) == 3, "1+2=3")
+    assert(add(0, 0) == 0, "0+0=0")
+    assert(add(-1, 1) == 0, "-1+1=0")
+
+fn test_mul():
+    assert(mul(3, 4) == 12, "3*4=12")
+    assert(mul(0, 5) == 0, "0*5=0")
+
+fn test_clamp():
+    assert(clamp(5, 0, 10) == 5, "within range")
+    assert(clamp(-1, 0, 10) == 0, "below min")
+    assert(clamp(15, 0, 10) == 10, "above max")
+
+fn test_average():
+    assert(average([2, 4, 6]) == 4, "average of 2,4,6")
+    assert(average([]) == 0, "empty list")
+
+fn test_safe_divide():
+    val ok = safeDivide(10, 2)
+    match ok:
+        when Ok(v):  assert(v == 5, "10/2=5")
+        when Err(e): assert(false, "unexpected error")
+    val err = safeDivide(10, 0)
+    match err:
+        when Ok(v):  assert(false, "expected error")
+        when Err(e): assert(e == "div by zero", "error message")
+
+fn test_pipe_operator():
+    val result = [1, 2, 3, 4, 5] |> filter(n -> n > 2) |> map(n -> n * 2)
+    assert(result.length == 3, "filter length")
+    assert(result[0] == 6, "first element")
+    assert(result[2] == 10, "last element")
+`
+
+  val fluxJson = {
+    name:        projectName,
+    version:     "1.0.0",
+    description: "A Flux Lang v" + VERSION + " project",
+    author:      "",
+    license:     "MIT",
+    entry:       "src/main.flux",
+    outDir:      "dist",
+    sourcemap:   false,
+    typecheck:   true,
+    scripts: {
+      start:  "flux run src/main.flux",
+      build:  "flux bundle src/main.flux -o dist/bundle.js",
+      dev:    "flux watch src/main.flux",
+      check:  "flux check src/main.flux",
+      test:   "flux test tests/",
+      fmt:    "flux fmt src/",
+      lint:   "flux lint src/",
+    },
+    dependencies:    {},
+    devDependencies: { "@xnoxs/flux-lang": "^" + VERSION },
+  }
+
+  val gitignore = "node_modules/\ndist/\nflux_modules/\n*.js.map\n.DS_Store\n"
+
+  val readme = `# {projectName}
+
+A project built with [Flux Lang](https://flux-lang.dev) v{VERSION} — the self-hosted compiler.
+
+## Quick Start
+
+\`\`\`bash
+flux run src/main.flux
+\`\`\`
+
+## Project Structure
+
+\`\`\`
+{projectName}/
+├── src/
+│   ├── main.flux        # Entry point
+│   └── utils.flux       # Utility functions
+├── tests/
+│   └── main.test.flux   # Test suite
+├── flux.json            # Project config
+└── README.md
+\`\`\`
+
+## Commands
+
+| Command | Description |
+|---|---|
+| \`flux run src/main.flux\` | Run the project |
+| \`flux bundle src/main.flux -o dist/bundle.js\` | Bundle to single file |
+| \`flux watch src/main.flux\` | Watch mode |
+| \`flux check src/main.flux\` | Type check + static analysis |
+| \`flux test tests/\` | Run all tests |
+| \`flux fmt src/\` | Format source code |
+| \`flux lint src/\` | Lint for issues |
+| \`flux add <package>\` | Add a dependency |
+`
+
+  val allFiles = [
+    projectName + "/src/main.flux",
+    projectName + "/src/utils.flux",
+    projectName + "/tests/main.test.flux",
+    projectName + "/flux.json",
+    projectName + "/.gitignore",
+    projectName + "/README.md",
+  ]
+
+  Fs.writeFileSync(Path.join(dir, "src", "main.flux"),        mainFlux,  "utf8")
+  Fs.writeFileSync(Path.join(dir, "src", "utils.flux"),       utilsFlux, "utf8")
+  Fs.writeFileSync(Path.join(dir, "tests", "main.test.flux"), testFlux,  "utf8")
+  Fs.writeFileSync(Path.join(dir, "flux.json"),   JSON.stringify(fluxJson, null, 2) + "\n", "utf8")
+  Fs.writeFileSync(Path.join(dir, ".gitignore"),  gitignore, "utf8")
+  Fs.writeFileSync(Path.join(dir, "README.md"),   readme, "utf8")
+
+  console.log()
+  console.log(green("✓ Created: ") + bold(projectName + "/"))
+  console.log()
+  console.log(gray("  Files:"))
+  for f in allFiles:
+    console.log("  " + cyan(f))
+  console.log()
+  console.log(bold("  Next steps:"))
+  console.log("    " + yellow("cd " + projectName))
+  console.log("    " + yellow("flux run src/main.flux"))
+  console.log()
+  console.log(gray("  Or run the test suite:"))
+  console.log("    " + yellow("flux test tests/"))
+  console.log()
+
+// ── flux self-hosted ──────────────────────────────────────────
+fn cmdSelfHosted(sub, opts):
+  val SELF = Path.join(__dirname, ".")
+
+  val coreModules = [
+    "css-preprocessor", "checker", "type-checker",
+    "jsx", "lexer", "parser", "codegen", "transpiler",
+  ]
+  val extModules = [
+    "formatter", "sourcemap", "stdlib", "mangler",
+    "linter", "bundler", "test-runner",
+  ]
+  val newModules = ["config", "pkg", "cli"]
+  val allModules = [...coreModules, ...extModules, ...newModules]
+
+  if sub == "build":
+    val { execSync } = require("child_process")
+    val BIN = Path.join(__dirname, "../../bin/flux.js")
+    console.log()
+    console.log(bold("⚡ Flux Bootstrap — Stage 0"))
+    console.log(gray("  Compiling self-hosted sources with stage-0 compiler...\n"))
+
+    var ok = 0
+    var failed = 0
+    for name in allModules:
+      val src = Path.join(SELF, name + ".flux")
+      val out = Path.join(SELF, name + ".js")
+      if not Fs.existsSync(src):
+        console.log(gray("  ○ " + name + ".flux  (skipped — not found)"))
+        continue
+      try:
+        val cmd = `node "${BIN}" compile "${src}" -o "${out}" --no-mangle`
+        execSync(cmd, { cwd: Path.join(__dirname, "../.."), stdio: "pipe" })
+        console.log(green("  ✓ ") + name + ".flux → " + gray(name + ".js"))
+        ok = ok + 1
+      catch(e):
+        console.error(red("  ✗ ") + name + ".flux — " + e.message.split("\n")[0])
+        failed = failed + 1
+
+    console.log()
+    if failed == 0:
+      console.log(green("✓ Bootstrap complete! ") + gray(ok + " modules compiled"))
+      console.log()
+      console.log("  Activate self-hosted mode:")
+      console.log("    " + yellow("FLUX_SELF_HOSTED=1 flux <command>"))
+    else:
+      console.log(red("✗ " + failed + " module(s) failed, " + ok + " succeeded"))
+    console.log()
+    return
+
+  if sub == "verify":
+    console.log(cyan("\n  Verifying self-hosted compiler output...\n"))
+    try:
+      val selfMod    = require(Path.join(SELF, "transpiler.js"))
+      val stage0Mod  = require(Path.join(__dirname, "../transpiler.js"))
+      val testSrc    = `fn greet(name): return "Hello, {name}!"\nval msg = greet("Flux")`
+      val r0 = stage0Mod.transpile(testSrc, {})
+      val r1 = selfMod.transpile(testSrc, {})
+      fn norm(s): return s.replace(/\/\/.*/g, "").replace(/\s+/g, " ").trim()
+      if norm(r0.output) == norm(r1.output):
+        console.log(green("✓ Self-hosted output matches stage-0!"))
+        console.log(green("✓ Flux is fully self-hosting."))
+      else:
+        console.log(yellow("⚠  Outputs differ (minor differences are OK)"))
+        console.log(gray("  Stage-0:    ") + r0.output.split("\n")[0])
+        console.log(gray("  Self-hosted:") + r1.output.split("\n")[0])
+    catch(e):
+      console.error(red("✗ Verify failed: " + e.message))
+    console.log()
+    return
+
+  // Default: show status
+  console.log()
+  console.log(bold("  Flux Self-Hosted Compiler Status\n"))
+  val selfActive = process.env.FLUX_SELF_HOSTED == "1"
+  if selfActive:
+    console.log("  Mode:    " + green("● ACTIVE") + gray("  (using self-hosted compiler)"))
+  else:
+    console.log("  Mode:    " + gray("○ INACTIVE") + "  " + gray("(using stage-0 compiler)"))
+    console.log("  Toggle:  " + yellow("FLUX_SELF_HOSTED=1 flux <command>"))
+    console.log("  Build:   " + yellow("flux self-hosted build"))
+
+  console.log()
+  console.log(bold("  Core Pipeline (" + coreModules.length + " modules)"))
+  for name in coreModules:
+    val jsPath  = Path.join(SELF, name + ".js")
+    val flxPath = Path.join(SELF, name + ".flux")
+    val hasJs   = Fs.existsSync(jsPath)
+    val hasFlx  = Fs.existsSync(flxPath)
+    val kb      = hasJs ? (Fs.statSync(jsPath).size / 1024).toFixed(1) : "?"
+    val sym     = hasJs ? green("✓") : red("✗")
+    val note    = not hasFlx ? gray("  (no .flux source)") : ""
+    console.log("    " + sym + " " + (name + ".flux").padEnd(26) + gray(kb + " KB") + note)
+
+  console.log()
+  console.log(bold("  Extended Toolchain (" + extModules.length + " modules)"))
+  for name in extModules:
+    val jsPath  = Path.join(SELF, name + ".js")
+    val flxPath = Path.join(SELF, name + ".flux")
+    val hasJs   = Fs.existsSync(jsPath)
+    val hasFlx  = Fs.existsSync(flxPath)
+    val kb      = hasJs ? (Fs.statSync(jsPath).size / 1024).toFixed(1) : "?"
+    val sym     = hasJs ? green("✓") : red("✗")
+    val note    = not hasFlx ? gray("  (no .flux source)") : ""
+    console.log("    " + sym + " " + (name + ".flux").padEnd(26) + gray(kb + " KB") + note)
+
+  console.log()
+  console.log(bold("  Ecosystem (" + newModules.length + " modules)"))
+  for name in newModules:
+    val jsPath  = Path.join(SELF, name + ".js")
+    val flxPath = Path.join(SELF, name + ".flux")
+    val hasJs   = Fs.existsSync(jsPath)
+    val hasFlx  = Fs.existsSync(flxPath)
+    val kb      = hasJs ? (Fs.statSync(jsPath).size / 1024).toFixed(1) : "?"
+    val sym     = hasJs ? green("✓") : yellow("○")
+    console.log("    " + sym + " " + (name + ".flux").padEnd(26) + (hasJs ? gray(kb + " KB") : yellow("not built")))
+
+  console.log()
+
+// ── flux version ─────────────────────────────────────────────
+fn cmdVersion(opts):
+  if noColor:
+    console.log("flux-lang v" + VERSION)
+    return
+  console.log(cyan(bold("⚡ Flux Lang")) + gray(" v" + VERSION + "  [" + STAGE + "]"))
+
+// ══════════════════════════════════════════════════════════════
+//  Main entry point
+// ══════════════════════════════════════════════════════════════
+
+fn main():
+  val { positional, opts } = parseArgs(process.argv)
+  val cmd = positional[0] ?? "help"
+
+  match cmd:
+    when "compile":   cmdCompile(positional[1], opts)
+    when "run":       cmdRun(positional[1], opts)
+    when "check":     cmdCheck(positional.slice(1), opts)
+    when "fmt":       cmdFmt(positional.slice(1), opts)
+    when "format":    cmdFmt(positional.slice(1), opts)
+    when "lint":      cmdLint(positional.slice(1), opts)
+    when "bundle":    cmdBundle(positional[1], opts)
+    when "watch":     cmdWatch(positional[1], opts)
+    when "tokens":    cmdTokens(positional[1], opts)
+    when "ast":       cmdAst(positional[1], opts)
+    when "repl":      cmdRepl(opts)
+    when "init":      cmdInit(positional[1], opts)
+    when "add":       cmdAdd(positional.slice(1), opts)
+    when "remove":    cmdRemove(positional.slice(1), opts)
+    when "rm":        cmdRemove(positional.slice(1), opts)
+    when "install":   cmdInstall(opts)
+    when "i":         cmdInstall(opts)
+    when "list":      cmdList(opts)
+    when "ls":        cmdList(opts)
+    when "search":    cmdSearch(positional[1], opts)
+    when "info":      cmdInfo(positional[1], opts)
+    when "publish":   cmdPublish(opts)
+    when "self-hosted": cmdSelfHosted(positional[1], opts)
+    when "version":   cmdVersion(opts)
+    when "-v":        cmdVersion(opts)
+    when "--version": cmdVersion(opts)
+    when "help":      showHelp()
+    when "--help":    showHelp()
+    when "-h":        showHelp()
+    when _:
+      console.error(red("✗ Unknown command: " + cmd))
+      console.error(gray("  Run: flux help"))
+      process.exit(1)
+
+main()