mygo-cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MyGo contributors
+
+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,56 @@
+# mygo-cli
+
+The `mygo` command line tool of [MyGo](https://github.com/egoist/mygo), the
+desktop app framework for Go on the system webview, as prebuilt binaries for
+macOS, Linux and Windows (arm64 and x64).
+
+Create a project, which depends on mygo-cli and runs it from its scripts:
+
+```sh
+bunx mygo-cli init my-app    # or: npx mygo-cli init my-app
+cd my-app
+bun run dev                  # mygo dev: the app with live reload
+bun run build                # mygo build: the packaged app
+```
+
+In a project that depends on mygo-cli, `bunx mygo <command>` runs its
+`mygo`. Or install it globally with `npm install -g mygo-cli`. The commands
+are those of the CLI installed with Go
+(`go install github.com/egoist/mygo/cmd/mygo@latest`): `init`, `dev`,
+`build`, `generate`, `keygen` and `doctor`. Building apps still needs
+[Go](https://go.dev/dl/), which compiles them.
+
+Outside such a project, run `bunx mygo-cli` or `npx mygo-cli` rather than
+`bunx mygo`: npm has an unrelated package named mygo.
+
+## How it works
+
+Each platform's binary is in a package of its own, such as
+`@egoist/mygo-cli-darwin-arm64`, which mygo-cli lists as an optional dependency:
+package managers install only the one that matches the machine. The `mygo`
+command then runs that binary. Set `MYGO_CLI_BINARY` to the path of another
+build of the CLI to use it instead.
+
+## mygo.config.ts
+
+`defineConfig` types the configuration of a project, `mygo.config.ts`:
+
+```ts
+import { defineConfig } from "mygo-cli";
+
+export default defineConfig({
+  name: "My App",
+  identifier: "com.example.myapp",
+  devUrl: "http://localhost:5173",
+});
+```
+
+## The binary
+
+From JavaScript, `binaryPath()` returns the path of the binary:
+
+```ts
+import { binaryPath } from "mygo-cli";
+
+Bun.spawnSync([binaryPath(), "generate"]);
+```

package/bin/mygo.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// Runs the mygo binary of this platform with the arguments of this script.
+import { spawn } from "node:child_process";
+import { binaryPath } from "../index.js";
+
+let bin;
+try {
+  bin = binaryPath();
+} catch (err) {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+}
+const args = process.argv.slice(2);
+
+if (process.platform !== "win32" && typeof process.execve === "function") {
+  // Become the binary (Node.js 23.11 and later, Bun), so that signals and
+  // the exit status are its own.
+  process.execve(bin, [bin, ...args]);
+}
+
+const child = spawn(bin, args, { stdio: "inherit" });
+// Ctrl+C reaches the binary from the terminal too: let it decide when to
+// exit, which mygo dev takes a moment for.
+process.on("SIGINT", () => {});
+process.on("SIGTERM", () => child.kill("SIGTERM"));
+child.on("error", (err) => {
+  console.error(`mygo-cli: cannot run ${bin}: ${err.message}`);
+  process.exit(1);
+});
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.removeAllListeners(signal);
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code ?? 1);
+  }
+});

package/index.d.ts

@@ -0,0 +1,179 @@
+/** The platforms with a prebuilt binary, as `${process.platform}-${process.arch}`. */
+export declare const platforms: readonly string[];
+
+/**
+ * Returns the name of the package holding the mygo binary of a platform,
+ * by default this one. Throws for platforms without a prebuilt binary.
+ */
+export declare function platformPackage(platform?: string, arch?: string): string;
+
+/**
+ * Returns the path of the mygo binary to run: $MYGO_CLI_BINARY when set,
+ * else the binary of this platform's package. Throws when that package is
+ * not installed.
+ */
+export declare function binaryPath(): string;
+
+/**
+ * Types the configuration of mygo.config.ts, which takes the place of
+ * mygo.json:
+ *
+ * ```ts
+ * import { defineConfig } from "mygo-cli";
+ *
+ * export default defineConfig({
+ *   name: "My App",
+ *   identifier: "com.example.myapp",
+ *   devUrl: "http://localhost:5173",
+ * });
+ * ```
+ *
+ * A function gets the command running and returns the configuration, or a
+ * promise of it.
+ */
+export declare function defineConfig(config: Config): Config;
+export declare function defineConfig(config: Promise<Config>): Promise<Config>;
+export declare function defineConfig(config: ConfigFn): ConfigFn;
+
+/** A configuration computed for the command running. */
+export type ConfigFn = (env: ConfigEnv) => Config | Promise<Config>;
+
+/** What a configuration function gets. */
+export interface ConfigEnv {
+  /** The mygo command running. */
+  command: "dev" | "build" | "generate" | "init";
+}
+
+/** The configuration of a MyGo project. Every field is optional. */
+export interface Config {
+  /** The name users see: the app, its executable, menus and installers (default: the directory's name). */
+  name?: string;
+  /**
+   * A reverse DNS name unique to the app, such as `com.example.myapp`, on
+   * which systems key preferences, permissions and registrations (default:
+   * `com.mygo.` and the name's letters and digits).
+   */
+  identifier?: string;
+  /** The version of the app, which updates compare (default: `0.1.0`). */
+  version?: string;
+  /** The copyright notice of the app. */
+  copyright?: string;
+  /** A square PNG, ideally 1024×1024 (default: `resources/icon.png` when it exists). */
+  icon?: string;
+  /** The Go package of the app, relative to the project (default: `.`). */
+  main?: string;
+  /** Where `mygo build` writes the builds, one directory per platform (default: `dist`). */
+  out?: string;
+  /**
+   * Where `mygo generate` writes the TypeScript client (default:
+   * `src/mygo.ts` when package.json is at the project root).
+   */
+  bindings?: string;
+
+  /**
+   * The dev server `mygo dev` points the app at, such as
+   * `http://localhost:5173`: windows load it for URLs without a scheme.
+   */
+  devUrl?: string;
+  /** Runs in the project while `mygo dev` runs, e.g. the dev server; the app starts once `devUrl` answers. */
+  devCommand?: string;
+  /** Builds the frontend before `mygo build` compiles the app. */
+  buildCommand?: string;
+  /**
+   * The directory of the built frontend, which `mygo build` embeds into the
+   * app; `mygo dev` serves it from disk without `devUrl`.
+   */
+  frontendDist?: string;
+
+  /**
+   * Files and directories copied into the app under their base names, next
+   * to the contents of the project's resources directory.
+   */
+  resources?: string[];
+  /** The URL schemes the app opens, such as `myapp` for `myapp://…`, which reach `App.OnOpenURL`. */
+  urlSchemes?: string[];
+  /** The types of files the app opens, which reach `App.OnOpenFile`. */
+  fileAssociations?: FileAssociation[];
+  /** Signed updates, which `mygo.Updater` installs. */
+  updates?: UpdatesConfig;
+  /** macOS packaging. */
+  macos?: MacOSConfig;
+  /** Windows packaging. */
+  windows?: WindowsConfig;
+  /** Linux packaging. */
+  linux?: LinuxConfig;
+}
+
+/** A type of file the app opens. */
+export interface FileAssociation {
+  /** The file name extensions, without dots, e.g. `["md"]`. */
+  ext: string[];
+  /** What the files are, e.g. `"Markdown Document"`. */
+  name?: string;
+  /** The MIME type of the files, by which Linux identifies them (default: `application/x-<app>-<ext>`). */
+  mimeType?: string;
+  /** The app's role for the files on macOS (default: `"Editor"`). */
+  role?: "Editor" | "Viewer";
+}
+
+/** Signed updates: `publicKey` and one of `github` and `url` are required. */
+export interface UpdatesConfig {
+  /** The contents of mygo-update.pub, from `mygo keygen`. */
+  publicKey: string;
+  /** A public GitHub repository, `owner/name`, whose releases hold the updates. */
+  github?: string;
+  /** What precedes the version in release tags (default: `v`). */
+  tagPrefix?: string;
+  /** Instead of `github`, the HTTPS URL of a directory holding the updates. */
+  url?: string;
+  /** The path of mygo-update.key; `MYGO_UPDATER_PRIVATE_KEY`, holding the key, takes precedence. */
+  privateKey?: string;
+  /** A Markdown file whose `## <version>` section becomes the release notes (default: `CHANGELOG.md` when it exists). */
+  changelog?: string;
+}
+
+/** macOS packaging. */
+export interface MacOSConfig {
+  /** The oldest macOS the app runs on (default: `12.0`). */
+  minimumSystemVersion?: string;
+  /** The identity that signs the app and its disk image, e.g. `Developer ID Application: Jane Doe (TEAMID)` (default: `-`, ad hoc). */
+  signingIdentity?: string;
+  /** A property list of entitlements to sign the app with. */
+  entitlements?: string;
+  /** Keys added to the app's Info.plist, replacing MyGo's, e.g. `NSCameraUsageDescription`. */
+  infoPlist?: Record<string, unknown>;
+  /** The volume name of the disk image (default: the name). */
+  dmgTitle?: string;
+  /** Notarizes production disk images. */
+  notarize?: NotarizeConfig;
+}
+
+/** Credentials of `xcrun notarytool store-credentials <profile>`. */
+export interface NotarizeConfig {
+  /** The profile holding the credentials. */
+  keychainProfile: string;
+  /** The keychain holding the profile (default: the login keychain). */
+  keychain?: string;
+}
+
+/** Windows packaging. */
+export interface WindowsConfig {
+  /** A code signing certificate (.pfx); its password comes from `MYGO_WINDOWS_CERTIFICATE_PASSWORD`. */
+  certificate?: string;
+  /** Instead of `certificate`, a command that signs a file, with `%1` for its path. */
+  signCommand?: string;
+  /** The time stamping server of `certificate` (default: `http://timestamp.digicert.com`). */
+  timestampUrl?: string;
+}
+
+/** Linux packaging. */
+export interface LinuxConfig {
+  /** `Name <email>`: makes `mygo build` create a Debian package. */
+  maintainer?: string;
+  /** A short description, for the desktop entry and the package. */
+  comment?: string;
+  /** The categories of the desktop entry (default: `["Utility"]`). */
+  categories?: string[];
+  /** Debian packages the app needs besides GTK and WebKitGTK. */
+  depends?: string[];
+}

package/index.js

@@ -0,0 +1,89 @@
+// mygo-cli ships the mygo command line tool of MyGo as a prebuilt binary
+// per platform. Each binary is in a package of its own,
+// @egoist/mygo-cli-<os>-<cpu>,
+// which mygo-cli lists as optional dependencies: package managers install
+// the one matching the machine's os and cpu fields.
+import { execFileSync } from "node:child_process";
+import { accessSync, chmodSync, constants, existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const here = dirname(fileURLToPath(import.meta.url));
+const { version } = require("./package.json");
+
+/** The platforms with a prebuilt binary, as `${process.platform}-${process.arch}`. */
+export const platforms = ["darwin-arm64", "darwin-x64", "linux-arm64", "linux-x64", "win32-arm64", "win32-x64"];
+
+const goInstall = `go install github.com/egoist/mygo/cmd/mygo@v${version}`;
+
+/**
+ * Returns the name of the package holding the mygo binary of a platform,
+ * by default this one.
+ */
+export function platformPackage(platform = process.platform, arch = process.arch) {
+  const target = `${platform}-${arch}`;
+  if (!platforms.includes(target)) {
+    throw new Error(`mygo-cli: there is no prebuilt mygo binary for ${target}; install the CLI with Go instead: ${goInstall}`);
+  }
+  return `@egoist/mygo-cli-${target}`;
+}
+
+/**
+ * Returns the path of the mygo binary to run: $MYGO_CLI_BINARY when set,
+ * else the binary of this platform's package. In a checkout of the MyGo
+ * repository it builds the CLI from its source first.
+ */
+export function binaryPath() {
+  if (process.env.MYGO_CLI_BINARY) return process.env.MYGO_CLI_BINARY;
+  const exe = process.platform === "win32" ? "mygo.exe" : "mygo";
+  const pkg = platformPackage();
+  const checkout = join(here, "..", "..");
+  if (isCheckout(checkout)) {
+    // The platform packages hold no binary until they are released: build
+    // the CLI from source, which Go's build cache makes quick.
+    const bin = join(here, "npm", `${process.platform}-${process.arch}`, "bin", exe);
+    execFileSync("go", ["build", "-o", bin, "./cmd/mygo"], { cwd: checkout, stdio: "inherit" });
+    return bin;
+  }
+  let dir;
+  try {
+    dir = dirname(require.resolve(`${pkg}/package.json`));
+  } catch {
+    throw new Error(
+      `mygo-cli: ${pkg}, the package with the mygo binary of this platform, is not installed. ` +
+        `Reinstall mygo-cli without omitting optional dependencies, or install the CLI with Go: ${goInstall}`,
+    );
+  }
+  const bin = join(dir, "bin", exe);
+  if (process.platform !== "win32") {
+    try {
+      accessSync(bin, constants.X_OK);
+    } catch {
+      // Some package managers drop the executable bit.
+      chmodSync(bin, 0o755);
+    }
+  }
+  return bin;
+}
+
+/**
+ * Types the configuration of mygo.config.ts: an object, or a function of the
+ * command running that returns one.
+ */
+export function defineConfig(config) {
+  return config;
+}
+
+/** Reports whether dir is a checkout of the MyGo repository. */
+function isCheckout(dir) {
+  try {
+    return (
+      readFileSync(join(dir, "go.mod"), "utf8").startsWith("module github.com/egoist/mygo\n") &&
+      existsSync(join(dir, "cmd", "mygo", "main.go"))
+    );
+  } catch {
+    return false;
+  }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "mygo-cli",
+  "version": "0.1.1",
+  "description": "The mygo command line tool: create, develop and package MyGo desktop apps",
+  "keywords": [
+    "mygo",
+    "desktop",
+    "webview",
+    "go",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/egoist/mygo.git",
+    "directory": "packages/cli"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "mygo": "bin/mygo.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "types": "./index.d.ts",
+  "files": [
+    "bin",
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "binaries": "bun run build.ts",
+    "test": "bun test"
+  },
+  "optionalDependencies": {
+    "@egoist/mygo-cli-darwin-arm64": "0.1.1",
+    "@egoist/mygo-cli-darwin-x64": "0.1.1",
+    "@egoist/mygo-cli-linux-arm64": "0.1.1",
+    "@egoist/mygo-cli-linux-x64": "0.1.1",
+    "@egoist/mygo-cli-win32-arm64": "0.1.1",
+    "@egoist/mygo-cli-win32-x64": "0.1.1"
+  }
+}