@junejs/cli 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 June.build
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# @junejs/cli
+
+The `june` command — dev, build, deploy, gen, info. **Preview (0.0.x): APIs
+will change.**
+
+```bash
+npm create june my-app    # scaffolds and wires this CLI locally
+cd my-app && npm run dev
+```
+
+```
+june dev      # dev server with watch + browser live-reload (--no-watch, --port)
+june build    # Cloudflare Workers bundle: dist/worker.js + prerendered assets
+june deploy   # build + wrangler upload (--dry-run validates only)
+june gen      # freeze content/**/*.md → app/_content.ts
+june info     # routes + the agent surface (MCP tools, discovery endpoints)
+```
+
+Runs on [Bun](https://bun.sh) (≥ 1.3) — the scaffolder itself (`npm create
+june`) runs on Node. Site & docs: [june.build](https://june.build) · every
+docs page is also markdown (append `.md`).

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@junejs/cli",
+  "version": "0.0.2",
+  "description": "The `june` CLI — dev / build / deploy / gen / info. A thin bin over @junejs/server.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://june.build",
+  "bin": {
+    "june": "./src/june.ts"
+  },
+  "exports": {
+    ".": "./src/cli.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@junejs/core": "0.0.0",
+    "@junejs/server": "0.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/junebuild/june"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,135 @@
+// The `june` CLI logic — host code (node:* allowed), a thin layer over
+// @junejs/server. Exposed as run(argv) so it is testable without spawning a
+// process; the bin (june.ts) just forwards process.argv. See docs/cli.md.
+
+import { join, resolve } from "node:path";
+
+export type Parsed = {
+  verb: string;
+  positional: string[];
+  flags: Record<string, string | boolean>;
+};
+
+// Minimal, dependency-free parser: `june <verb> [dir] [--flag] [--flag value]`.
+export function parse(argv: string[]): Parsed {
+  const [verb = "", ...rest] = argv;
+  const positional: string[] = [];
+  const flags: Record<string, string | boolean> = {};
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i]!;
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = rest[i + 1];
+      if (next !== undefined && !next.startsWith("--")) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+  return { verb, positional, flags };
+}
+
+const HELP = `june — the agent-native React framework
+
+Usage: june <command> [dir] [options]
+
+Commands:
+  dev      Start the dev server                 --port <n> --no-watch
+  build    Build a workerd-ready bundle         --out <dir>
+  deploy   Build + deploy (Workers)             --dry-run
+  gen      Freeze content/schema                --check
+  info     Show routes + the agent surface
+  help     Show this help
+
+The app directory defaults to the current directory.
+`;
+
+function appRoot(positional: string[]): string {
+  return positional[0] ? resolve(positional[0]) : process.cwd();
+}
+
+async function info(root: string): Promise<number> {
+  const { createApp, loadJuneConfig } = await import("@junejs/server");
+  const { resolveAgent } = await import("@junejs/core/config");
+  const { ACTION_REGISTRY } = await import("@junejs/core/agent");
+
+  const config = await loadJuneConfig(root);
+  const app = createApp({ appDir: join(root, "app"), config });
+  await app.warmup(); // register defineAction side effects so tools show up
+  const routes = await app.routePaths();
+  const agent = resolveAgent(config.agent);
+  const tools = [...ACTION_REGISTRY.values()].filter((a) => a.description).map((a) => a.id);
+
+  console.log(`June app: ${config.site?.name ?? "(unnamed)"}`);
+  console.log(`\nRoutes (${routes.length}):`);
+  for (const r of routes) console.log(`  ${r}`);
+  if (agent.enabled) {
+    console.log(`\nAgent surface:`);
+    if (agent.discovery) console.log(`  discovery  /llms.txt · /sitemap.xml · /.well-known/api-catalog`);
+    if (agent.mcp) console.log(`  mcp        /mcp  (tools: ${tools.length ? tools.join(", ") : "none"})`);
+  } else {
+    console.log(`\nAgent surface: disabled`);
+  }
+  return 0;
+}
+
+// Returns an exit code for one-shot commands, or undefined for long-running
+// ones (dev) so the bin does NOT call process.exit and the server stays alive.
+export async function run(argv: string[]): Promise<number | undefined> {
+  const { verb, positional, flags } = parse(argv);
+  const root = appRoot(positional);
+
+  switch (verb) {
+    case "dev": {
+      // A restart is the reload: the watch supervisor respawns the serving
+      // child on file change (see watch.ts). Children carry JUNE_DEV_CHILD.
+      if (!process.env.JUNE_DEV_CHILD && !flags["no-watch"]) {
+        const { superviseDev } = await import("./watch");
+        return superviseDev(root);
+      }
+      const { startDevServer } = await import("@junejs/server");
+      await startDevServer({
+        appDir: join(root, "app"),
+        port: flags.port ? Number(flags.port) : 3000,
+      });
+      return undefined; // server keeps the process alive
+    }
+    case "build": {
+      const { juneBuild } = await import("@junejs/server");
+      const out = typeof flags.out === "string" ? { outDir: resolve(flags.out) } : {};
+      const r = await juneBuild(root, out);
+      console.log(
+        `built ${r.outFile}  (${r.routes.length} routes, ${r.dynamicRoutes.length} dynamic, ${r.prerendered.length} prerendered)`,
+      );
+      return 0;
+    }
+    case "deploy": {
+      const { juneDeploy } = await import("@junejs/server");
+      const r = await juneDeploy(root, { dryRun: !!flags["dry-run"] });
+      console.log(r.url ? `deployed → ${r.url}` : r.dryRun ? "dry-run ok" : "deployed");
+      return 0;
+    }
+    case "gen": {
+      const { generateContent } = await import("@junejs/server");
+      const cols = await generateContent(root);
+      console.log(cols.length ? `generated content: ${cols.join(", ")}` : "no content/ collections");
+      return 0;
+    }
+    case "info":
+      return info(root);
+    case "":
+    case "help":
+    case "--help":
+    case "-h":
+      console.log(HELP);
+      return 0;
+    default:
+      console.error(`june: unknown command "${verb}"\n`);
+      console.log(HELP);
+      return 1;
+  }
+}

package/src/june.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env bun
+// The `june` bin. Thin: parse argv → run(). Long-running commands (dev) resolve
+// to undefined so we do NOT exit and the server keeps the process alive.
+import { run } from "./cli";
+
+run(process.argv.slice(2))
+  .then((code) => {
+    if (code !== undefined) process.exit(code);
+  })
+  .catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+  });

package/src/watch.ts

@@ -0,0 +1,87 @@
+// `june dev` watch supervisor — a restart IS the reload mechanism. The host's
+// ESM module cache cannot be invalidated (re-importing an edited file is a
+// cached no-op), so the only honest reload is a fresh process: the supervisor
+// watches the app root and respawns the server child on change. Push-based
+// HMR belongs to the native runtime track; this is the Bun/Node host's story.
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { watch } from "node:fs";
+import { sep } from "node:path";
+
+const IGNORED_DIRS = new Set(["node_modules", ".git", "dist", ".june"]);
+
+// Exported for tests. `app/_content.*` is generated by `june gen` — watching
+// it would loop (content change → regen → _content event → regen …).
+export function ignoredPath(file: string): boolean {
+  const parts = file.split(sep);
+  if (parts.some((p) => IGNORED_DIRS.has(p))) return true;
+  return parts.length === 2 && parts[0] === "app" && /^_content\.[^/]+$/.test(parts[1]!);
+}
+
+export function superviseDev(root: string): undefined {
+  let child: ChildProcess | undefined;
+  let restarting = false;
+
+  const start = () => {
+    // Respawn this exact invocation (bin + argv) with the child marker set.
+    child = spawn(process.execPath, process.argv.slice(1), {
+      stdio: "inherit",
+      env: { ...process.env, JUNE_DEV_CHILD: "1" },
+    });
+    child.on("exit", (code) => {
+      if (restarting) return;
+      // Died on its own (e.g. a broken june.config.ts). Stay alive: the next
+      // save restarts it — exiting here would make the user re-run dev by hand.
+      console.error(`[june] dev server exited (${code ?? "?"}) — waiting for changes`);
+      child = undefined;
+    });
+  };
+
+  const restart = async (file: string) => {
+    if (restarting) return; // an edit mid-restart is picked up by the next save
+    restarting = true;
+    if (file.startsWith(`content${sep}`)) {
+      // The frozen manifest must be fresh BEFORE the new server boots.
+      try {
+        const { generateContent } = await import("@junejs/server");
+        await generateContent(root);
+      } catch (err) {
+        console.error("[june] content regen failed:", err);
+      }
+    }
+    console.log(`[june] ${file} changed — restarting`);
+    const c = child;
+    if (!c || c.exitCode !== null || c.signalCode !== null) {
+      // The child is already dead (crash state) — once("exit") on an exited
+      // process never fires, which would park `restarting` forever. Just
+      // bring a fresh one up.
+      restarting = false;
+      start();
+      return;
+    }
+    c.once("exit", () => {
+      restarting = false;
+      start();
+    });
+    c.kill();
+  };
+
+  let pending: string | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  watch(root, { recursive: true }, (_event, file) => {
+    if (!file || ignoredPath(file)) return;
+    pending = file;
+    clearTimeout(timer);
+    timer = setTimeout(() => void restart(pending!), 80);
+  });
+
+  for (const sig of ["SIGINT", "SIGTERM"] as const) {
+    process.on(sig, () => {
+      child?.kill(sig);
+      process.exit(0);
+    });
+  }
+
+  start();
+  return undefined;
+}