@junejs/cli 0.0.52-dev.2 → 0.1.0-dev.4

package/bin.mjs

@@ -3,7 +3,8 @@
 // (src/june.ts) runs on Bun, and without this hop an npm user without Bun
 // gets a bare shebang error ("env: bun: No such file or directory") instead
 // of a sentence telling them what to install.
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
+import { constants } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -20,5 +21,27 @@ if (probe.error || probe.status !== 0) {
   process.exit(1);
 }
 
-const child = spawnSync("bun", [entry, ...args], { stdio: "inherit", shell: false });
-process.exit(child.status ?? 1);
+// An async child, so this process can relay what is sent to ITS pid: a supervisor's SIGTERM,
+// a closed terminal's SIGHUP, a SIGINT sent to the pid alone. Waiting in spawnSync, Node died
+// on the signal and left Bun — and whatever Bun runs (`june dev`, an external subcommand) —
+// orphaned. Relayed once, while the child runs; it exits on its own terms and we mirror it.
+// SIGINT is always caught (so we wait for the child) but relayed only without a terminal:
+// Ctrl-C in a terminal already reaches the whole foreground group, and a second SIGINT would
+// turn a graceful stop into a forced one.
+const child = spawn("bun", [entry, ...args], { stdio: "inherit", shell: false });
+const relay = (signal) => {
+  if (child.exitCode === null && child.signalCode === null) child.kill(signal);
+};
+process.on("SIGTERM", () => relay("SIGTERM"));
+process.on("SIGHUP", () => relay("SIGHUP"));
+process.on("SIGINT", () => {
+  if (!process.stdin.isTTY) relay("SIGINT");
+});
+child.on("error", (err) => {
+  console.error(`june: could not start bun: ${err.message}`);
+  process.exit(1);
+});
+// A child killed by a signal exits the shell way, 128 + the signal number.
+child.on("exit", (code, signal) => {
+  process.exit(code ?? (signal ? 128 + (constants.signals[signal] ?? 0) : 1));
+});

package/dist/cli.d.ts

@@ -1,10 +1,9 @@
 //#region src/cli.d.ts
-type Parsed = {
+export type Parsed = {
   verb: string;
   positional: string[];
   flags: Record<string, string | boolean>;
 };
-declare function parse(argv: string[]): Parsed;
-declare function run(argv: string[]): Promise<number | undefined>;
-//#endregion
-export { Parsed, parse, run };
+export declare function parse(argv: string[]): Parsed;
+export declare function run(argv: string[]): Promise<number | undefined>;
+//#endregion

package/dist/cli.js

@@ -37,6 +37,9 @@ Commands:
   help     Show this help
 
 The app directory defaults to the current directory.
+
+Any other command runs \`june-<command>\` from node_modules/.bin (this directory or
+a parent) or PATH, with the arguments as given — e.g. \`june inbox\` runs june-inbox.
 `;
 function appRoot(positional) {
 	return positional[0] ? resolve(positional[0]) : process.cwd();
@@ -59,8 +62,12 @@ async function info(root) {
 	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.discovery) {
+			console.log(`  discovery  /llms.txt · /sitemap.xml · /.well-known/api-catalog`);
+			console.log(`             /.well-known/ai-catalog.json · /.well-known/agent-skills/index.json`);
+		}
 		if (agent.mcp) console.log(`  mcp        /mcp  (tools: ${tools.length ? tools.join(", ") : "none"})`);
+		if (agent.api) console.log(`  api        POST /api/<tool> · /openapi.json`);
 	} else console.log(`\nAgent surface: disabled`);
 	return 0;
 }
@@ -75,7 +82,7 @@ async function run(argv) {
 				return 1;
 			}
 			if (!process.env.JUNE_DEV_CHILD && !flags["no-watch"]) {
-				const { superviseDev } = await import("./watch-CeyzNVKv.js");
+				const { superviseDev } = await import("./watch-BcQz4ONx.js");
 				return superviseDev(root);
 			}
 			const { startDevServer } = await import("@junejs/server");
@@ -107,7 +114,7 @@ async function run(argv) {
 			if (!flags.check && existsSync(join(root, "app"))) {
 				const cols = await generateContent(root);
 				console.log(cols.length ? `generated content: ${cols.join(", ")}` : "no content/ collections");
-				const { generateMessages } = await import("./messages-DfAlYpfN.js");
+				const { generateMessages } = await import("./messages-CofbPnix.js");
 				const locales = await generateMessages(root);
 				if (locales) console.log(`generated messages: ${locales.join(", ")}`);
 			}
@@ -159,7 +166,8 @@ async function run(argv) {
 					console.log("nothing to generate");
 					return 0;
 				}
-				await writeFile(join(dbRoot, "db", "schema.d.ts"), text);
+				const out = join(dbRoot, "db", "schema.d.ts");
+				await writeFile(out, text);
 				console.log("wrote db/schema.d.ts");
 				return 0;
 			}
@@ -171,12 +179,16 @@ async function run(argv) {
 		case "help":
 		case "--help":
 		case "-h":
-			console.log(HELP);
+			console.log(HELP + (await import("./external-BOQj7SFk.js")).firstPartyHelp());
 			return 0;
-		default:
-			console.error(`june: unknown command "${verb}"\n`);
+		default: {
+			const { findExternal, runExternal, unknownVerbMessage } = await import("./external-BOQj7SFk.js");
+			const bin = findExternal(verb, process.cwd());
+			if (bin) return runExternal(bin, argv.slice(1));
+			console.error(`${unknownVerbMessage(verb)}\n`);
 			console.log(HELP);
 			return 1;
+		}
 	}
 }
 //#endregion

package/dist/external-BOQj7SFk.js

@@ -0,0 +1,94 @@
+import { delimiter, dirname, join, resolve } from "node:path";
+//#region src/external.ts
+const FIRST_PARTY = {};
+const VERB = /^[a-z][a-z0-9-]*$/;
+function findExternal(verb, cwd, envPath = process.env.PATH ?? "") {
+	if (!VERB.test(verb)) return null;
+	const dirs = [];
+	for (let dir = resolve(cwd);; dir = dirname(dir)) {
+		dirs.push(join(dir, "node_modules", ".bin"));
+		if (dirname(dir) === dir) break;
+	}
+	return Bun.which(`june-${verb}`, { PATH: [...dirs, envPath].join(delimiter) });
+}
+const CMD_META = /([()\][%!^"`<>&|;, *?])/g;
+function escapeCmdCommand(command) {
+	return command.replace(CMD_META, "^$1");
+}
+function escapeCmdArgument(arg, doubleEscape) {
+	let out = arg.replace(/(?=(\\+?)?)\1"/g, "$1$1\\\"").replace(/(?=(\\+?)?)\1$/, "$1$1");
+	out = `"${out}"`.replace(CMD_META, "^$1");
+	return doubleEscape ? out.replace(CMD_META, "^$1") : out;
+}
+function externalCommand(bin, args, platform = process.platform) {
+	if (platform !== "win32" || !/\.(cmd|bat)$/i.test(bin)) return {
+		argv: [bin, ...args],
+		verbatim: false
+	};
+	const shim = /node_modules[\\/]\.bin[\\/][^\\/]+\.cmd$/i.test(bin);
+	const line = [escapeCmdCommand(bin), ...args.map((a) => escapeCmdArgument(a, shim))].join(" ");
+	return {
+		argv: [
+			process.env.ComSpec ?? "cmd.exe",
+			"/d",
+			"/s",
+			"/c",
+			`"${line}"`
+		],
+		verbatim: true
+	};
+}
+async function runExternal(bin, args) {
+	const { argv, verbatim } = externalCommand(bin, args);
+	const proc = Bun.spawn(argv, {
+		stdio: [
+			"inherit",
+			"inherit",
+			"inherit"
+		],
+		env: { ...process.env },
+		windowsVerbatimArguments: verbatim
+	});
+	const forward = (signal) => () => proc.kill(signal);
+	const onTerm = forward("SIGTERM");
+	const onHup = forward("SIGHUP");
+	const onInt = () => {
+		if (!process.stdin.isTTY) proc.kill("SIGINT");
+	};
+	process.on("SIGTERM", onTerm);
+	process.on("SIGHUP", onHup);
+	process.on("SIGINT", onInt);
+	try {
+		const code = await proc.exited;
+		if (proc.signalCode) {
+			const n = signalNumber(proc.signalCode);
+			return n ? 128 + n : 1;
+		}
+		return code;
+	} finally {
+		process.off("SIGTERM", onTerm);
+		process.off("SIGHUP", onHup);
+		process.off("SIGINT", onInt);
+	}
+}
+function signalNumber(signal) {
+	return {
+		SIGHUP: 1,
+		SIGINT: 2,
+		SIGKILL: 9,
+		SIGTERM: 15
+	}[signal] ?? 0;
+}
+function firstPartyHelp(firstParty = FIRST_PARTY) {
+	const entries = Object.entries(firstParty);
+	if (!entries.length) return "";
+	const width = Math.max(...entries.map(([v]) => v.length));
+	return `\nFirst-party external commands (install the package to use them):\n` + entries.map(([verb, e]) => `  ${verb.padEnd(width)}  ${e.summary}  (${e.package})`).join("\n") + "\n";
+}
+function unknownVerbMessage(verb, firstParty = FIRST_PARTY) {
+	const known = Object.hasOwn(firstParty, verb) ? firstParty[verb] : void 0;
+	if (known) return `june ${verb}: ${known.summary} — provided by ${known.package}, which isn't installed.\n  install it in this app:  bun add -d ${known.package}\n  or run it without installing:  bunx ${known.package}`;
+	return `june: unknown command "${verb}" (no built-in command, and no june-${verb} in node_modules/.bin or on PATH)`;
+}
+//#endregion
+export { findExternal, firstPartyHelp, runExternal, unknownVerbMessage };

package/dist/{messages-DfAlYpfN.js → messages-CofbPnix.js}

@@ -11,7 +11,8 @@ async function generateMessages(root) {
 	if (!existsSync(messagesDir)) return null;
 	let codegen;
 	try {
-		codegen = await import(pathToFileURL(createRequire(resolve(root, "package.json")).resolve("@junejs/i18n/codegen")).href);
+		const resolved = createRequire(resolve(root, "package.json")).resolve("@junejs/i18n/codegen");
+		codegen = await import(pathToFileURL(resolved).href);
 	} catch {
 		console.warn("[june] messages/ found but @junejs/i18n is not installed — skipping (run: bun add @junejs/i18n)");
 		return null;

package/dist/{watch-CeyzNVKv.js → watch-BcQz4ONx.js}

@@ -41,7 +41,7 @@ function superviseDev(root) {
 			console.error("[june] content regen failed:", err);
 		}
 		if (file.startsWith(`messages${sep}`)) try {
-			const { generateMessages } = await import("./messages-DfAlYpfN.js");
+			const { generateMessages } = await import("./messages-CofbPnix.js");
 			await generateMessages(root);
 		} catch (err) {
 			console.error("[june] messages regen failed:", err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junejs/cli",
-  "version": "0.0.52-dev.2",
+  "version": "0.1.0-dev.4",
   "description": "The `june` CLI — dev / build / deploy / gen / info. A thin bin over @junejs/server.",
   "type": "module",
   "license": "MIT",
@@ -27,8 +27,8 @@
     "build": "tsdown"
   },
   "dependencies": {
-    "@junejs/core": ">=0.2.0-dev.33",
-    "@junejs/server": ">=1.0.0-dev.15"
+    "@junejs/core": ">=0.2.0-dev.62",
+    "@junejs/server": ">=1.0.0-dev.41"
   },
   "repository": {
     "type": "git",

package/src/cli.ts

@@ -49,6 +49,9 @@ Commands:
   help     Show this help
 
 The app directory defaults to the current directory.
+
+Any other command runs \`june-<command>\` from node_modules/.bin (this directory or
+a parent) or PATH, with the arguments as given — e.g. \`june inbox\` runs june-inbox.
 `;
 
 function appRoot(positional: string[]): string {
@@ -72,8 +75,12 @@ async function info(root: string): Promise<number> {
   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.discovery) {
+      console.log(`  discovery  /llms.txt · /sitemap.xml · /.well-known/api-catalog`);
+      console.log(`             /.well-known/ai-catalog.json · /.well-known/agent-skills/index.json`);
+    }
     if (agent.mcp) console.log(`  mcp        /mcp  (tools: ${tools.length ? tools.join(", ") : "none"})`);
+    if (agent.api) console.log(`  api        POST /api/<tool> · /openapi.json`);
   } else {
     console.log(`\nAgent surface: disabled`);
   }
@@ -221,11 +228,17 @@ export async function run(argv: string[]): Promise<number | undefined> {
     case "help":
     case "--help":
     case "-h":
-      console.log(HELP);
+      console.log(HELP + (await import("./external")).firstPartyHelp());
       return 0;
-    default:
-      console.error(`june: unknown command "${verb}"\n`);
+    default: {
+      // Not built in: an external subcommand (#295) — `june-<verb>` from node_modules/.bin or
+      // PATH, handed the arguments exactly as typed (june's own parser never sees them).
+      const { findExternal, runExternal, unknownVerbMessage } = await import("./external");
+      const bin = findExternal(verb, process.cwd());
+      if (bin) return runExternal(bin, argv.slice(1));
+      console.error(`${unknownVerbMessage(verb)}\n`);
       console.log(HELP);
       return 1;
+    }
   }
 }

package/src/external.ts

@@ -0,0 +1,115 @@
+// External subcommands (#295, docs/rfc-email.md §9.3): `june <verb>` that is not built in
+// runs `june-<verb>` — the git / cargo model. Looked up in the app's node_modules/.bin (from
+// the working directory up, where a package manager may hoist it), then on PATH. Only the
+// binary the user named runs: nothing is scanned or imported in-process, a client versions
+// and ships on its own, it works for an operator without the app's repository, and the
+// exec boundary survives `june` becoming a native binary.
+
+import { delimiter, dirname, join, resolve } from "node:path";
+
+// First-party external verbs: listed in `june help`, and named in the error when one is
+// invoked but not installed. A verb joins when its package is published.
+export type ExternalVerb = { package: string; summary: string };
+export const FIRST_PARTY: Record<string, ExternalVerb> = {};
+
+// A verb names a binary: lowercase, no separators or dots, so `june ../x` never resolves.
+const VERB = /^[a-z][a-z0-9-]*$/;
+
+// The `june-<verb>` binary to run, or null. node_modules/.bin directories nearest first,
+// then PATH; Bun.which applies PATHEXT on Windows (npm's .cmd shims, bun's .exe ones).
+export function findExternal(verb: string, cwd: string, envPath = process.env.PATH ?? ""): string | null {
+  if (!VERB.test(verb)) return null;
+  const dirs: string[] = [];
+  for (let dir = resolve(cwd); ; dir = dirname(dir)) {
+    dirs.push(join(dir, "node_modules", ".bin"));
+    if (dirname(dir) === dir) break;
+  }
+  return Bun.which(`june-${verb}`, { PATH: [...dirs, envPath].join(delimiter) });
+}
+
+// ── Windows: running a .cmd/.bat through cmd.exe ──────────────────────────────
+// cmd.exe re-parses the command line: `&`, `|`, `%`, `^`, `<`, `>` in an argument would split
+// it or run another command (the "BatBadBut" class, CVE-2024-27980) — an argument that
+// carries outside text, say an email a coding agent passes along, must reach the command
+// literally. This is cross-spawn's escaping (MIT, github.com/moxystudio/node-cross-spawn):
+// each argument is quoted with its backslashes and quotes escaped, then every cmd.exe
+// metacharacter is ^-escaped — twice for a node_modules/.bin shim, because the shim's `%*`
+// hands the arguments to one more parse. The line goes to cmd.exe verbatim (no quoting of
+// our own on top).
+const CMD_META = /([()\][%!^"`<>&|;, *?])/g;
+
+function escapeCmdCommand(command: string): string {
+  return command.replace(CMD_META, "^$1");
+}
+
+function escapeCmdArgument(arg: string, doubleEscape: boolean): string {
+  // Backslashes before a quote, or at the end, are doubled so they stay literal once quoted.
+  let out = arg.replace(/(?=(\\+?)?)\1"/g, '$1$1\\"').replace(/(?=(\\+?)?)\1$/, "$1$1");
+  out = `"${out}"`.replace(CMD_META, "^$1");
+  return doubleEscape ? out.replace(CMD_META, "^$1") : out;
+}
+
+// The argv (and whether it is verbatim) to spawn `bin` with `args`.
+export function externalCommand(bin: string, args: string[], platform = process.platform): { argv: string[]; verbatim: boolean } {
+  if (platform !== "win32" || !/\.(cmd|bat)$/i.test(bin)) return { argv: [bin, ...args], verbatim: false };
+  const shim = /node_modules[\\/]\.bin[\\/][^\\/]+\.cmd$/i.test(bin);
+  const line = [escapeCmdCommand(bin), ...args.map((a) => escapeCmdArgument(a, shim))].join(" ");
+  return { argv: [process.env.ComSpec ?? "cmd.exe", "/d", "/s", "/c", `"${line}"`], verbatim: true };
+}
+
+// Run it with the arguments exactly as typed and the terminal inherited; resolves to its exit
+// code. A signal that stops `june` (a supervisor's SIGTERM, a closed terminal's SIGHUP) is
+// passed on, so the external command is not left running. SIGINT is always caught — `june`
+// waits for the command to finish its own shutdown — but passed on only without a terminal:
+// Ctrl-C in a terminal already reaches the command (same foreground group), and a second
+// SIGINT would turn its graceful stop into a forced one.
+export async function runExternal(bin: string, args: string[]): Promise<number> {
+  const { argv, verbatim } = externalCommand(bin, args);
+  // env passed explicitly: Bun.spawn otherwise misses variables set on process.env after
+  // startup (a caller that sets JUNE_TOKEN in-process before delegating, say).
+  const proc = Bun.spawn(argv, { stdio: ["inherit", "inherit", "inherit"], env: { ...process.env }, windowsVerbatimArguments: verbatim });
+  const forward = (signal: NodeJS.Signals) => () => proc.kill(signal);
+  const onTerm = forward("SIGTERM");
+  const onHup = forward("SIGHUP");
+  const onInt = () => { if (!process.stdin.isTTY) proc.kill("SIGINT"); };
+  process.on("SIGTERM", onTerm);
+  process.on("SIGHUP", onHup);
+  process.on("SIGINT", onInt);
+  try {
+    const code = await proc.exited;
+    // Killed by a signal: the shell convention, 128 + the signal number (1 if unrecognized).
+    if (proc.signalCode) {
+      const n = signalNumber(proc.signalCode);
+      return n ? 128 + n : 1;
+    }
+    return code;
+  } finally {
+    process.off("SIGTERM", onTerm);
+    process.off("SIGHUP", onHup);
+    process.off("SIGINT", onInt);
+  }
+}
+
+function signalNumber(signal: string): number {
+  return ({ SIGHUP: 1, SIGINT: 2, SIGKILL: 9, SIGTERM: 15 } as Record<string, number>)[signal] ?? 0;
+}
+
+// The first-party external verbs, as `june help` lists them; empty when there are none.
+export function firstPartyHelp(firstParty: Record<string, ExternalVerb> = FIRST_PARTY): string {
+  const entries = Object.entries(firstParty);
+  if (!entries.length) return "";
+  const width = Math.max(...entries.map(([v]) => v.length));
+  return `\nFirst-party external commands (install the package to use them):\n` +
+    entries.map(([verb, e]) => `  ${verb.padEnd(width)}  ${e.summary}  (${e.package})`).join("\n") + "\n";
+}
+
+// The error for a verb that is neither built in nor installed.
+export function unknownVerbMessage(verb: string, firstParty: Record<string, ExternalVerb> = FIRST_PARTY): string {
+  const known = Object.hasOwn(firstParty, verb) ? firstParty[verb] : undefined;
+  if (known) {
+    return `june ${verb}: ${known.summary} — provided by ${known.package}, which isn't installed.\n` +
+      `  install it in this app:  bun add -d ${known.package}\n` +
+      `  or run it without installing:  bunx ${known.package}`;
+  }
+  return `june: unknown command "${verb}" (no built-in command, and no june-${verb} in node_modules/.bin or on PATH)`;
+}