nomen-lang 0.0.7 → 0.0.8

package/package.json

@@ -1,31 +1,34 @@
 {
-	"name": "nomen-lang",
-	"version": "0.0.7",
-	"description": "The CLI for the Nomen programming language.",
-	"keywords": [],
-	"license": "ISC",
-	"author": "",
-	"bin": {
-		"nomen": "dist/index.mjs"
-	},
-	"type": "module",
-	"scripts": {
-		"build": "vp pack",
-		"dev": "vp pack --watch",
-		"test": "vp test",
-		"check": "vp check",
-		"format": "vp check --fix",
-		"prepare": "vp config",
-		"go": "tsx src/index.ts",
-		"register": "pnpm build && pnpm add -g ."
-	},
-	"devDependencies": {
-		"@types/node": "^26.1.2",
-		"@types/yargs": "^17.0.35",
-		"chokidar": "^5.0.0",
-		"tsx": "^4.23.1",
-		"typescript": "^7.0.2",
-		"vite-plus": "catalog:",
-		"yargs": "^18.1.0"
-	}
-}
+  "name": "nomen-lang",
+  "version": "0.0.8",
+  "description": "The CLI for the Nomen programming language.",
+  "keywords": [],
+  "license": "ISC",
+  "author": "",
+  "bin": {
+    "nomen": "dist/index.mjs"
+  },
+  "files": [
+    "dist",
+    "src",
+    "core",
+    "NOMEN_AGENTS.md"
+  ],
+  "type": "module",
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "chokidar": "^5.0.0",
+    "tsx": "^4.23.1",
+    "typescript": "^7.0.2",
+    "vite-plus": "0.2.7"
+  },
+  "scripts": {
+    "build": "node scripts/bundle-assets.mjs && vp pack",
+    "dev": "node scripts/bundle-assets.mjs && vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "format": "vp check --fix",
+    "go": "tsx src/index.ts",
+    "register": "pnpm build && pnpm add -g ."
+  }
+}

package/src/args.ts

@@ -0,0 +1,171 @@
+export interface Args {
+	command: string | undefined;
+	name?: string;
+	in?: string;
+	out?: string;
+	config?: string;
+	watch: boolean;
+	filter?: string;
+	arch: string;
+	platform?: string;
+	lib?: string;
+	audit: boolean;
+	audit_runtime?: string;
+	check: boolean;
+}
+
+// Canonical option name for each accepted long/short spelling.
+const STRING_OPTIONS: Map<string, string> = new Map([
+	["in", "in"],
+	["i", "in"],
+	["out", "out"],
+	["o", "out"],
+	["config", "config"],
+	["c", "config"],
+	["filter", "filter"],
+	["f", "filter"],
+	["arch", "arch"],
+	["a", "arch"],
+	["platform", "platform"],
+	["p", "platform"],
+	["lib", "lib"],
+	["l", "lib"],
+	["audit-runtime", "audit_runtime"],
+]);
+
+const BOOLEAN_OPTIONS: Map<string, string> = new Map([
+	["watch", "watch"],
+	["w", "watch"],
+	["audit", "audit"],
+	["check", "check"],
+]);
+
+const DEFAULTS: Partial<Args> = {
+	arch: "aarch64",
+	watch: false,
+	audit: false,
+	check: false,
+};
+
+function set(args: Args, key: string, value: string | boolean): void {
+	(args as unknown as Record<string, string | boolean>)[key] = value;
+}
+
+/** Parse `argv` (excluding the node binary and script path) into an `Args` object. */
+export function parse_args(argv: string[] = process.argv.slice(2)): Args {
+	const args: Args = { command: undefined, ...DEFAULTS } as Args;
+	const positional: string[] = [];
+	let only_positional = false;
+
+	const next_value = (i: number, spelling: string): string => {
+		if (i + 1 >= argv.length) throw new Error(`Option ${spelling} requires a value`);
+		return argv[i + 1];
+	};
+
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+
+		if (only_positional) {
+			positional.push(arg);
+			continue;
+		}
+
+		if (arg === "--") {
+			only_positional = true;
+			continue;
+		}
+
+		if (arg === "-h" || arg === "--help") {
+			print_help();
+			process.exit(0);
+		}
+
+		// Long option: --name, --name=value, or --name value
+		if (arg.startsWith("--") && arg.length > 2) {
+			const eq = arg.indexOf("=");
+			const name = eq === -1 ? arg.slice(2) : arg.slice(2, eq);
+			const inline = eq === -1 ? undefined : arg.slice(eq + 1);
+
+			if (STRING_OPTIONS.has(name)) {
+				const key = STRING_OPTIONS.get(name)!;
+				set(args, key, inline !== undefined ? inline : next_value(i, `--${name}`));
+				if (inline === undefined) i++;
+			} else if (BOOLEAN_OPTIONS.has(name)) {
+				const key = BOOLEAN_OPTIONS.get(name)!;
+				set(args, key, inline === undefined ? true : inline !== "false");
+			} else {
+				throw new Error(`Unknown option: --${name}`);
+			}
+			continue;
+		}
+
+		// Short option(s): -i value, -ivalue, -i=value, or combined -wv
+		if (arg.startsWith("-") && arg.length > 1 && !/^-\d/.test(arg)) {
+			const chars = arg.slice(1);
+			for (let j = 0; j < chars.length; j++) {
+				const c = chars[j];
+
+				if (c === "h") {
+					print_help();
+					process.exit(0);
+				}
+
+				if (STRING_OPTIONS.has(c)) {
+					const key = STRING_OPTIONS.get(c)!;
+					const rest = chars.slice(j + 1);
+					if (rest.length > 0) {
+						set(args, key, rest.startsWith("=") ? rest.slice(1) : rest);
+					} else {
+						set(args, key, next_value(i, `-${c}`));
+						i++;
+					}
+					break;
+				}
+
+				if (BOOLEAN_OPTIONS.has(c)) {
+					set(args, BOOLEAN_OPTIONS.get(c)!, true);
+					continue;
+				}
+
+				throw new Error(`Unknown option: -${c}`);
+			}
+			continue;
+		}
+
+		positional.push(arg);
+	}
+
+	args.command = positional[0];
+	args.name = positional[1];
+	return args;
+}
+
+export function print_help(): void {
+	console.log(
+		[
+			"Usage:",
+			"  nomen run --in [file/folder]     Parse, check, build and run a program",
+			"  nomen build --in [file/folder]    Parse, check and build (no run)",
+			"  nomen check --in [file/folder]    Parse and check only",
+			"  nomen format [--in folder]        Reformat every .nm file",
+			"  nomen docs [--in file]            Generate markdown documentation",
+			"  nomen test [--in folder]          Discover and run *.test.nm files",
+			"  nomen init <name>                 Scaffold a new project in ./<name>",
+			"  nomen lib-path                    Print the bundled System library path",
+			"",
+			"Options:",
+			"  --in, -i <path>         Input file or folder",
+			"  --out, -o <path>        Output file",
+			"  --config, -c <path>     Path to a config file",
+			"  --watch, -w             Watch for file changes",
+			"  --filter, -f <regex>    Only run test files whose path matches this regex",
+			"  --arch, -a <arch>       Target architecture: aarch64 | c (default: aarch64)",
+			"  --platform, -p <name>   Target platform: macos, ios, linux, android, windows, web",
+			"  --lib, -l <path>        Path to System library directory (containing package.jsonc)",
+			"  --audit                 Audit the generated program for memory issues",
+			"  --audit-runtime <path>  Path to audit_runtime.c, linked in when --audit is set",
+			"  --check                 For `nomen format`: report files that would change",
+			"  -h, --help              Show this help",
+		].join("\n"),
+	);
+}

package/src/index.ts

@@ -4,16 +4,16 @@ import fs from "node:fs";
 import path from "node:path";
 
 import chokidar from "chokidar";
-import { hideBin } from "yargs/helpers";
-import yargs from "yargs/yargs";
 
 import build, { default_platform } from "../../src/build.ts";
 import { format_source, type FormatOptions } from "../../src/format.ts";
 import join from "../../src/join.ts";
 import { get_library } from "../../src/lib.ts";
 import parse from "../../src/parse.ts";
+import { parse_args, print_help, type Args } from "./args.ts";
 import { run_docs } from "./docs.ts";
 import render_errors, { render_warnings } from "./format_errors.ts";
+import { find_bundled, run_init } from "./init.ts";
 import { runTests } from "./test.ts";
 import type Config from "./types/Config.ts";
 
@@ -73,100 +73,48 @@ let build_root: string | undefined;
 
 console.log("\n~ NOMEN ~\n");
 
-const parser = yargs(hideBin(process.argv))
-	.usage(
-		"Usage:\n" +
-			"  nomen run --in [file/folder]    Parse, check, build and run a program\n" +
-			"  nomen build --in [file/folder]   Parse, check and build (no run)\n" +
-			"  nomen check --in [file/folder]   Parse and check only\n" +
-			"  nomen format [--in folder]       Reformat every .nm file\n" +
-			"  nomen docs [--in file]           Generate markdown documentation",
-	)
-	.command("run", "Parse, check, build and run a program")
-	.command("build", "Parse, check and build (compile and link, but do not run)")
-	.command("check", "Parse and check only")
-	.command("format", "Reformat every .nm file")
-	.command("docs", "Generate markdown documentation")
-	.command("test", "Discover and run *.test.nm files with the Tester harness")
-	.option("in", {
-		alias: "i",
-		describe: "Input file or folder",
-		type: "string",
-	})
-	.option("out", {
-		alias: "o",
-		describe: "Output file",
-		type: "string",
-	})
-	.option("config", {
-		alias: "c",
-		describe: "The path to a config file",
-		type: "string",
-	})
-	.option("watch", {
-		alias: "w",
-		describe: "Whether to watch for file changes",
-		type: "boolean",
-	})
-	.option("filter", {
-		alias: "f",
-		describe: "Only run test files whose path matches this regex",
-		type: "string",
-	})
-	.option("arch", {
-		alias: "a",
-		describe: "Target architecture (aarch64 or c)",
-		type: "string",
-		default: "aarch64",
-	})
-	.option("platform", {
-		alias: "p",
-		describe: "Target platform (macos, ios, linux, android, windows, web)",
-		type: "string",
-	})
-	.option("lib", {
-		alias: "l",
-		describe: "Path to System library directory (containing package.jsonc)",
-		type: "string",
-	})
-	.option("audit", {
-		describe: "Whether to audit the generated program for memory issues",
-		type: "boolean",
-	})
-	.option("audit-runtime", {
-		describe: "Path to audit_runtime.c, linked in when --audit is set",
-		type: "string",
-	})
-	.option("check", {
-		describe: "For `nomen format`: report files that would change without writing them",
-		type: "boolean",
-	})
-	.help(true);
-
-const options = parser.parseSync();
-
-const command = options._[0];
+const args: Args = parse_args();
+const command = args.command;
 
 try {
+	// `nomen init <name>` scaffolds a new project under ./<name>.
+	if (command === "init") {
+		run_init(args.name);
+		process.exit(0);
+	}
+
+	// `nomen lib-path` prints the absolute path to the System library
+	// bundled with this CLI. Used by tooling (e.g. the VS Code extension)
+	// to locate the standard library for projects without a local one.
+	if (command === "lib-path") {
+		const lib = find_bundled("core");
+		if (lib) {
+			process.stdout.write(lib + "\n");
+			process.exit(0);
+		}
+		console.log("No bundled System library found alongside the CLI.");
+		process.exit(1);
+	}
+
 	// `nomen docs` generates markdown documentation instead of compiling.
 	if (command === "docs") {
-		run_docs(typeof options.in === "string" ? options.in : undefined);
+		run_docs(args.in);
 		process.exit(0);
 	}
 
 	// `nomen test` discovers and runs every `*.test.nm` file under --in (or
 	// the cwd), compiling each into a Tester harness and reporting results.
 	if (command === "test") {
-		const root = options.in ?? process.cwd();
-		const filter = typeof options.filter === "string" ? new RegExp(options.filter) : undefined;
-		const arch = (options.arch as string | undefined) ?? "aarch64";
+		const root = args.in ?? process.cwd();
+		const filter = args.filter ? new RegExp(args.filter) : undefined;
+		const arch = args.arch ?? "aarch64";
 		const ok = runTests(root, { arch, filter });
 		process.exit(ok ? 0 : 1);
 	}
 
 	// `nomen format` re-indents and tidies every .nm file under a folder.
 	if (command === "format") {
-		const root = options.in ?? process.cwd();
+		const root = args.in ?? process.cwd();
 		const format_options = load_format_options(root);
 		const files = collect_nm_files(root);
 		let changed = 0;
@@ -178,7 +126,7 @@ try {
 				continue;
 			}
 			if (result.changed) {
-				if (!options.check) fs.writeFileSync(file, result.code);
+				if (!args.check) fs.writeFileSync(file, result.code);
 				changed += 1;
 				console.log(`Formatted ${file}`);
 			}
@@ -196,59 +144,59 @@ try {
 	else if (command === "check") mode = "check";
 
 	if (!mode) {
-		parser.showHelp("log");
+		print_help();
 		process.exit(1);
 	}
 
 	// An explicit --in wins; otherwise discover what to compile from the
 	// working folder — a package.jsonc `entry`, or a lone .nm file.
-	options.in = options.in ?? resolve_input();
-	if (!options.in) {
+	args.in = args.in ?? resolve_input();
+	if (!args.in) {
 		process.exit(0);
 	}
 	// For an explicit --in, build next to whatever was passed (the folder
 	// itself, or the file's folder). Discovery cases set build_root themselves.
 	if (!build_root) {
-		build_root = fs.lstatSync(options.in).isDirectory() ? options.in : path.dirname(options.in);
+		build_root = fs.lstatSync(args.in).isDirectory() ? args.in : path.dirname(args.in);
 	}
 
-	if (fs.existsSync(options.in)) {
+	if (fs.existsSync(args.in)) {
 		let config: Config = { arch: "aarch64", platform: default_platform() };
 		// Load the config from a file
-		if (options.config && fs.existsSync(options.config)) {
-			config = JSON.parse(fs.readFileSync(options.config, "utf-8"));
+		if (args.config && fs.existsSync(args.config)) {
+			config = JSON.parse(fs.readFileSync(args.config, "utf-8"));
 		}
 		// Overwrite with args
-		if (options.arch) config.arch = options.arch as "aarch64" | "c";
-		if (options.platform) config.platform = options.platform as string;
-		if (options.lib) config.lib = options.lib;
-		if (options.audit) config.audit = options.audit;
-		if (options["audit-runtime"]) config.audit_runtime = options["audit-runtime"];
+		if (args.arch) config.arch = args.arch as "aarch64" | "c";
+		if (args.platform) config.platform = args.platform;
+		if (args.lib) config.lib = args.lib;
+		if (args.audit) config.audit = args.audit;
+		if (args.audit_runtime) config.audit_runtime = args.audit_runtime;
 
 		// Is the --in path a folder
-		if (fs.lstatSync(options.in).isDirectory()) {
-			if (options.watch) {
-				watchPath(options.in, config, mode);
+		if (fs.lstatSync(args.in).isDirectory()) {
+			if (args.watch) {
+				watchPath(args.in, config, mode);
 			} else {
-				processFolder(options.in, config, mode);
+				processFolder(args.in, config, mode);
 			}
 		} else {
 			// Process the supplied file
-			const extname = path.extname(options.in);
-			if (shouldProcessFile(options.in)) {
+			const extname = path.extname(args.in);
+			if (shouldProcessFile(args.in)) {
 				// NOTE: We get add notifications for all watched files immediately
 				// TODO: Is this the case on Windows etc too?
-				if (options.watch) {
-					watchPath(options.in, config, mode);
+				if (args.watch) {
+					watchPath(args.in, config, mode);
 				} else {
-					processFile(options.in, config, mode);
+					processFile(args.in, config, mode);
 				}
 			} else {
 				console.log("Unsupported file type: " + extname);
 			}
 		}
 	} else {
-		console.log("Path not found: " + options.in);
+		console.log("Path not found: " + args.in);
 	}
 } catch (err) {
 	console.log("UH", err);
@@ -320,7 +268,8 @@ function resolve_lib(file_path: string): string | undefined {
 		if (parent === dir) break;
 		dir = parent;
 	}
-	return undefined;
+	// Nothing local — fall back to the System library bundled with the CLI.
+	return find_bundled("core");
 }
 
 function resolve_audit_runtime(config: Config, input_path: string): string | undefined {

package/src/init.ts

@@ -0,0 +1,128 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// A name must be a portable folder name: letters, digits, underscore and
+// hyphen only. Anything else (slashes, spaces, dots) would either break the
+// filesystem layout or produce an invalid package name.
+const NAME_RE = /^[A-Za-z][A-Za-z0-9_-]*$/;
+
+const GITIGNORE = `build/
+`;
+
+function package_jsonc(name: string): string {
+	return `{
+	"name": "${name}",
+	"entry": "src/main.nm"
+	// The System library is resolved automatically from your nomen-lang
+	// install. To pin a local checkout instead, uncomment:
+	// "imports": { "System": "../core" }
+}
+`;
+}
+
+const MAIN_NM = `import System
+
+pub func main = (Init init) {
+	Console.write("Hello world!\\n")
+}
+`;
+
+const TEST_NM = `import System
+import System/Test
+
+func add = (int a, int b, out int) => a + b
+
+pub func test_smoke = (ref Tester t) {
+	t.expect(add(2, 2) == 4, "2 + 2 should equal 4")
+}
+`;
+
+function readme(name: string): string {
+	return `# ${name}
+
+A [Nomen](https://github.com/andrewjk/nomen) project.
+
+## Build
+
+\`\`\`bash
+nomen build
+\`\`\`
+
+## Run
+
+\`\`\`bash
+nomen run
+\`\`\`
+
+## Test
+
+\`\`\`bash
+nomen test
+\`\`\`
+`;
+}
+
+// Resolve a bundled asset (core/ or NOMEN_AGENTS.md) shipped alongside the
+// CLI. In the published package these sit next to dist/; in the dev tree they
+// live one level up (the repo root), so check both.
+export function find_bundled(filename: string): string | undefined {
+	const here = path.dirname(fileURLToPath(import.meta.url));
+	const cli_root = path.dirname(here);
+	const candidates = [path.join(cli_root, filename), path.join(cli_root, "..", filename)];
+	for (const c of candidates) {
+		if (fs.existsSync(c)) return path.resolve(c);
+	}
+	return undefined;
+}
+
+/**
+ * `nomen init <name>`: scaffold a new project under `./<name>` with a sensible
+ * starting layout (package.jsonc, src/main.nm, a starter test, README and an
+ * AGENTS.md copied from the bundled NOMEN_AGENTS.md template).
+ */
+export function run_init(name: string | undefined): void {
+	if (!name) {
+		console.log("Usage: nomen init <name>");
+		process.exit(1);
+	}
+	if (!NAME_RE.test(name)) {
+		console.log(
+			`Invalid project name "${name}". Use letters, digits, '-' or '_' (must start with a letter).`,
+		);
+		process.exit(1);
+	}
+
+	const target = path.resolve(process.cwd(), name);
+	if (fs.existsSync(target)) {
+		console.log(`Already exists: ${target}`);
+		process.exit(1);
+	}
+
+	const agents_template = find_bundled("NOMEN_AGENTS.md");
+	if (!agents_template) {
+		console.log("Could not locate NOMEN_AGENTS.md template alongside the CLI.");
+		process.exit(1);
+	}
+
+	const src = path.join(target, "src");
+	const test = path.join(target, "test");
+	fs.mkdirSync(src, { recursive: true });
+	fs.mkdirSync(test, { recursive: true });
+
+	fs.writeFileSync(path.join(target, ".gitignore"), GITIGNORE);
+	fs.writeFileSync(path.join(target, "package.jsonc"), package_jsonc(name));
+	fs.writeFileSync(path.join(src, "main.nm"), MAIN_NM);
+	fs.writeFileSync(path.join(test, "smoke.test.nm"), TEST_NM);
+	fs.writeFileSync(path.join(target, "README.md"), readme(name));
+	fs.writeFileSync(path.join(target, "AGENTS.md"), fs.readFileSync(agents_template));
+
+	console.log(`Created ${name}/`);
+	console.log(`  ${name}/.gitignore`);
+	console.log(`  ${name}/package.jsonc`);
+	console.log(`  ${name}/src/main.nm`);
+	console.log(`  ${name}/test/smoke.test.nm`);
+	console.log(`  ${name}/README.md`);
+	console.log(`  ${name}/AGENTS.md`);
+	console.log(`\nNext: cd ${name} && nomen run`);
+}

package/src/test.ts

@@ -7,6 +7,7 @@ import build from "../../src/build.ts";
 import join from "../../src/join.ts";
 import { get_library } from "../../src/lib.ts";
 import parse from "../../src/parse.ts";
+import { find_bundled } from "./init.ts";
 
 const RECORD_PREFIX = "\\nomen|";
 
@@ -504,8 +505,10 @@ function resolve_lib_for(root: string): string | undefined {
 				}
 			}
 		}
+		// A bare `<dir>/System` is only the library if it has a package.jsonc;
+		// otherwise we'd match macOS's `/System` on the way to the root.
 		const systemDir = path.join(dir, "System");
-		if (fs.existsSync(systemDir)) return systemDir;
+		if (fs.existsSync(path.join(systemDir, "package.jsonc"))) return systemDir;
 		const globalSystem = path.join(dir, "core", "System");
 		if (fs.existsSync(globalSystem)) {
 			return path.join(dir, "core");
@@ -514,5 +517,6 @@ function resolve_lib_for(root: string): string | undefined {
 		if (parent === dir) break;
 		dir = parent;
 	}
-	return undefined;
+	// Nothing local — fall back to the System library bundled with the CLI.
+	return find_bundled("core");
 }