@ycs77/devbox 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Lucas Yang <yangchenshin77@gmail.com>
+
+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,5 @@
+# @ycs77/devbox
+
+## License
+
+[MIT LICENSE](LICENSE)

package/dist/cli.js

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { defineCommand, runCommand } from "citty";
+import { randomUUID } from "node:crypto";
+import { link, lstat, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, parse, relative, sep } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+//#region src/result.ts
+function success(value) {
+	return {
+		ok: true,
+		value
+	};
+}
+function failure(error) {
+	return {
+		ok: false,
+		error
+	};
+}
+
+//#endregion
+//#region src/host.ts
+const execFile$1 = promisify(execFile);
+const supportedHostAction = "Run Devbox from 64-bit WSL2 with Docker Desktop and Docker Compose available.";
+function currentHostEnvironment() {
+	return {
+		platform: process.platform,
+		arch: process.arch,
+		procVersion: () => readFile("/proc/version", "utf8"),
+		run: async (file, args) => {
+			await execFile$1(file, args);
+		}
+	};
+}
+async function validateSupportedHost(environment = currentHostEnvironment()) {
+	if (environment.platform !== "linux" || environment.arch !== "x64") return failure({
+		kind: "validation",
+		code: "unsupported-host",
+		observed: `Devbox supports only WSL2 linux/amd64; detected ${environment.platform}/${environment.arch}.`,
+		nextAction: supportedHostAction
+	});
+	let procVersion;
+	try {
+		procVersion = await environment.procVersion();
+	} catch {
+		return failure({
+			kind: "validation",
+			code: "unsupported-host",
+			observed: "Devbox could not verify that this Linux host is WSL2.",
+			nextAction: supportedHostAction
+		});
+	}
+	if (!/microsoft|wsl/i.test(procVersion)) return failure({
+		kind: "validation",
+		code: "unsupported-host",
+		observed: "Devbox supports WSL2, but this Linux host is not WSL2.",
+		nextAction: supportedHostAction
+	});
+	for (const [file, args, description] of [[
+		"docker",
+		["--version"],
+		"Docker"
+	], [
+		"docker",
+		["compose", "version"],
+		"Docker Compose"
+	]]) try {
+		await environment.run(file, args);
+	} catch {
+		return failure({
+			kind: "validation",
+			code: "missing-host-prerequisite",
+			observed: `${description} is unavailable.`,
+			nextAction: supportedHostAction
+		});
+	}
+	return success(void 0);
+}
+
+//#endregion
+//#region src/project.ts
+function projectStateDirectory(projectRoot, devboxHome) {
+	const root = parse(projectRoot).root;
+	const pathWithinRoot = relative(root, projectRoot);
+	if (!isAbsolute(projectRoot) || pathWithinRoot === ".." || pathWithinRoot.startsWith(`..${sep}`)) throw new TypeError("Project root must be an absolute path.");
+	return join(devboxHome, "projects", pathWithinRoot === "" ? "root" : pathWithinRoot.split(sep).map(escapePathSegment).join("-"));
+}
+function escapePathSegment(segment) {
+	const bytes = new TextEncoder().encode(segment);
+	let escaped = "";
+	for (const byte of bytes) if (byte >= 65 && byte <= 90 || byte >= 97 && byte <= 122 || byte >= 48 && byte <= 57 || byte === 45 || byte === 95) escaped += String.fromCharCode(byte);
+	else escaped += `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+	return escaped;
+}
+async function initializeProject(input = {}) {
+	const projectRoot = input.root ?? process.cwd();
+	const rootCheck = await validateProjectRoot(projectRoot);
+	if (!rootCheck.ok) return rootCheck;
+	if (input.signal?.aborted) throw new InterruptedError();
+	const hostCheck = await (input.validateHost ?? validateSupportedHost)();
+	if (!hostCheck.ok) return hostCheck;
+	if (input.signal?.aborted) throw new InterruptedError();
+	const stateDirectory = projectStateDirectory(projectRoot, input.devboxHome ?? join(homedir(), ".devbox"));
+	const configurationPath = join(stateDirectory, "config.yaml");
+	try {
+		await mkdir(stateDirectory, {
+			recursive: true,
+			mode: 448
+		});
+	} catch {
+		return failure({
+			kind: "operational",
+			code: "state-directory-unavailable",
+			observed: `Devbox could not create its Project state directory: ${stateDirectory}.`,
+			nextAction: "Check write access to ~/.devbox and run devbox init again."
+		});
+	}
+	if (input.signal?.aborted) throw new InterruptedError();
+	const temporaryPath = join(stateDirectory, `.config-${process.pid}-${randomUUID()}.tmp`);
+	const content = `version: 1\nprojectRoot: ${JSON.stringify(projectRoot)}\n`;
+	try {
+		await writeFile(temporaryPath, content, {
+			encoding: "utf8",
+			flag: "wx",
+			mode: 384
+		});
+		await link(temporaryPath, configurationPath);
+		await unlink(temporaryPath);
+		return success({
+			root: projectRoot,
+			stateDirectory,
+			created: true
+		});
+	} catch (cause) {
+		await unlink(temporaryPath).catch(() => void 0);
+		if (isFileExistsError(cause)) return success({
+			root: projectRoot,
+			stateDirectory,
+			created: false
+		});
+		return failure({
+			kind: "operational",
+			code: "registration-write-failed",
+			observed: `Devbox could not register this Project in ${stateDirectory}.`,
+			nextAction: "Check write access to ~/.devbox and run devbox init again."
+		});
+	}
+}
+async function validateProjectRoot(projectRoot) {
+	if (!isAbsolute(projectRoot)) return failure({
+		kind: "validation",
+		code: "invalid-project-root",
+		observed: `The current Project directory is not absolute: ${projectRoot}.`,
+		nextAction: "Run devbox init from an existing directory."
+	});
+	try {
+		if (!(await lstat(projectRoot)).isDirectory()) return failure({
+			kind: "validation",
+			code: "invalid-project-root",
+			observed: `The current Project path is not a directory: ${projectRoot}.`,
+			nextAction: "Run devbox init from an existing directory."
+		});
+	} catch {
+		return failure({
+			kind: "validation",
+			code: "missing-project-root",
+			observed: `The current Project directory does not exist: ${projectRoot}.`,
+			nextAction: "Change to an existing directory and run devbox init again."
+		});
+	}
+	return success(void 0);
+}
+function isFileExistsError(error) {
+	return typeof error === "object" && error !== null && error.code === "EEXIST";
+}
+var InterruptedError = class extends Error {
+	constructor() {
+		super("Devbox command interrupted.");
+	}
+};
+
+//#endregion
+//#region src/cli.ts
+const initCommand = defineCommand({
+	meta: {
+		name: "init",
+		description: "Register the current directory as a Devbox Project."
+	},
+	run: async (context) => {
+		if (context.rawArgs.length > 0) return failure({
+			kind: "usage",
+			code: "unexpected-init-arguments",
+			observed: "devbox init does not accept arguments.",
+			nextAction: "Run devbox init without arguments."
+		});
+		const registration = await context.data.initializeProject();
+		if (!registration.ok) return registration;
+		return {
+			ok: true,
+			value: {
+				projectRoot: registration.value.root,
+				created: registration.value.created
+			}
+		};
+	}
+});
+const rootCommand = defineCommand({
+	meta: {
+		name: "devbox",
+		description: "Prepare and run the Devbox Node Toolchain."
+	},
+	args: { command: {
+		type: "positional",
+		required: true
+	} },
+	run: async (context) => {
+		if (context.args.command !== "init") return failure({
+			kind: "usage",
+			code: "unknown-command",
+			observed: `Unknown command: ${context.args.command}.`,
+			nextAction: "Run devbox --help to see available commands."
+		});
+		const { result } = await runCommand(initCommand, {
+			rawArgs: context.rawArgs.slice(1),
+			data: context.data
+		});
+		return result;
+	}
+});
+async function runCli(rawArgs, dependencies = { initializeProject }) {
+	if (rawArgs.length === 1 && (rawArgs[0] === "--help" || rawArgs[0] === "-h")) return {
+		ok: true,
+		value: {
+			projectRoot: "",
+			created: false
+		}
+	};
+	try {
+		const { result } = await runCommand(rootCommand, {
+			rawArgs: [...rawArgs],
+			data: dependencies
+		});
+		return result;
+	} catch (error) {
+		if (error instanceof InterruptedError) throw error;
+		return failure({
+			kind: "usage",
+			code: "invalid-command-usage",
+			observed: error instanceof Error ? error.message : "Invalid Devbox command usage.",
+			nextAction: "Run devbox --help to see available commands."
+		});
+	}
+}
+function present(result, output = process) {
+	if (!result.ok) {
+		output.stderr.write(`${result.error.observed}\n${result.error.nextAction}\n`);
+		return result.error.kind === "usage" ? 2 : 1;
+	}
+	if (result.value.projectRoot === "") {
+		output.stdout.write("Usage: devbox init\n\nRegister the current directory as a Devbox Project.\n");
+		return 0;
+	}
+	output.stdout.write(result.value.created ? `Registered Project: ${result.value.projectRoot}\n` : `Project is already registered: ${result.value.projectRoot}\n`);
+	return 0;
+}
+async function main() {
+	const abortController = new AbortController();
+	const interrupt = () => abortController.abort();
+	process.once("SIGINT", interrupt);
+	try {
+		const result = await runCli(process.argv.slice(2), { initializeProject: () => initializeProject({ signal: abortController.signal }) });
+		process.exitCode = present(result);
+	} catch (error) {
+		if (error instanceof InterruptedError || abortController.signal.aborted) {
+			process.stderr.write("Devbox command interrupted.\n");
+			process.exitCode = 130;
+			return;
+		}
+		process.stderr.write("Devbox encountered an unexpected failure. Run devbox init again.\n");
+		process.exitCode = 1;
+	} finally {
+		process.off("SIGINT", interrupt);
+	}
+}
+if (process.argv[1] !== void 0 && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) await main();
+
+//#endregion
+export { present, runCli };

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@ycs77/devbox",
+  "version": "0.1.0",
+  "description": "Devbox Node-only MVP CLI",
+  "homepage": "https://github.com/ycs77/devbox",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ycs77/devbox.git",
+    "directory": "packages/devbox"
+  },
+  "bin": {
+    "devbox": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "citty": "^0.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "oxfmt": "^0.62.0",
+    "oxlint": "^1.77.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "tsdown": "^0.15.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "oxlint",
+    "fmt": "oxfmt",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "check": "pnpm lint && pnpm fmt --check && pnpm typecheck && pnpm test --run"
+  }
+}