@quickgui/cli 0.0.1

package/README.md

@@ -0,0 +1,72 @@
+# @quickgui/cli
+
+Project scaffolding, development, and production packaging for QuickGUI applications written with
+Solid 2.
+
+```console
+bunx @quickgui/cli init my-app
+cd my-app
+bun run dev
+```
+
+## Development
+
+`quickgui dev` creates a genuine native development application. On macOS this is an ad-hoc-signed
+`.app` under `.quickgui/dev/<target>/` and the CLI runs its `Contents/MacOS` executable.
+
+Each development build compiles two Bun entrypoints into the bundle's executable: a minimal native
+main-thread host and the current TS/TSX application Worker. Source edits create and sign a candidate
+`.app`; after its first native window completes an event-loop turn, the CLI stops the prior process.
+A compile or startup failure leaves the prior app running. The generated `.app` is self-contained
+and can also be launched directly from Finder or LaunchServices.
+
+AppKit/Winit stays permanently on the process main thread. Bun timers, fetch, streaming, and other
+application work stay on the Worker's supported event loop. Bounded native queues and an explicit
+Winit wake connect them without an idle polling interval.
+
+QuickGUI uses candidate-first process restart instead of in-isolate hot replacement because
+AppKit/Winit application state is process-owned.
+
+## Production builds
+
+`quickgui build` compiles the application, Solid renderer, Bun runtime, and target N-API addon into
+a self-contained executable. A production macOS target emits a signed `.app` and a versioned `.dmg`
+created with `create-dmg` under `dist/<target>/`; disk-image creation requires Node.js 20 or later.
+
+```console
+bun run build --target darwin-arm64
+bun run build --target windows-x64
+bun run build --sign "Developer ID Application: Example (TEAMID)" --notarize quickgui-notary
+```
+
+A target build requires the installed `@quickgui/native` package to contain that target's addon.
+`--notarize` names credentials previously stored with `xcrun notarytool store-credentials`; the CLI
+waits for acceptance, staples the DMG, and validates the ticket. The same profile can be configured
+as `macos.notarization.keychainProfile`.
+
+## Configuration
+
+```ts
+import { defineConfig } from "@quickgui/cli";
+
+export default defineConfig({
+  name: "My App",
+  identifier: "com.example.my-app",
+  entry: "src/app.tsx",
+  version: "0.1.0",
+  resources: ["assets"],
+  protocols: ["my-app"],
+  macos: {
+    icon: "assets/AppIcon.icns",
+    minimumSystemVersion: "13.0",
+    signingIdentity: "Developer ID Application: Example (TEAMID)",
+    notarization: { keychainProfile: "quickgui-notary" },
+  },
+});
+```
+
+`protocols` is written into a signed macOS app's `CFBundleURLTypes`. On Windows and Linux, register
+the same scheme at runtime with `DeepLink.register(...)`; macOS registration is intentionally
+declarative because Launch Services reads it from the application bundle.
+
+See the [CLI guide](../../docs/cli.md) for every command and option.

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@quickgui/cli",
+  "version": "0.0.1",
+  "description": "Project, development, and packaging CLI for QuickGUI",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/egoist/quickgui.git",
+    "directory": "packages/cli"
+  },
+  "bugs": "https://github.com/egoist/quickgui/issues",
+  "homepage": "https://github.com/egoist/quickgui#readme",
+  "type": "module",
+  "bin": {
+    "quickgui": "src/cli.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src/args.ts",
+    "src/build.ts",
+    "src/cli.ts",
+    "src/config.ts",
+    "src/dev.ts",
+    "src/error.ts",
+    "src/index.ts",
+    "src/init.ts",
+    "src/targets.ts",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@quickgui/native": "0.0.1",
+    "@quickgui/solid": "0.0.1",
+    "create-dmg": "^8.1.0"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "os": [
+    "darwin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT OR Apache-2.0"
+}

package/src/args.ts

@@ -0,0 +1,182 @@
+import { CliError } from "./error.ts";
+import { parseTarget, type QuickGuiTarget } from "./targets.ts";
+
+export type ParsedCliCommand =
+  | { command: "help"; topic?: "init" | "dev" | "build" }
+  | { command: "version" }
+  | {
+      command: "init";
+      directory: string;
+      install: boolean;
+      name?: string;
+      identifier?: string;
+    }
+  | {
+      command: "dev";
+      project: string;
+      configFile: string;
+      once: boolean;
+      launch: boolean;
+      target?: QuickGuiTarget;
+      signingIdentity?: string;
+    }
+  | {
+      command: "build";
+      project: string;
+      configFile: string;
+      target?: QuickGuiTarget;
+      outDir?: string;
+      signingIdentity?: string;
+      notarizationProfile?: string;
+    };
+
+interface OptionSpec {
+  key: string;
+  value: boolean;
+}
+
+interface ParsedOptions {
+  values: Map<string, string | true>;
+  positionals: string[];
+}
+
+export function parseCliArgs(argv: string[]): ParsedCliCommand {
+  if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+    return { command: "help" };
+  }
+  if (argv[0] === "--version" || argv[0] === "-v") return { command: "version" };
+
+  const command = argv[0];
+  const rest = argv.slice(1);
+  if (command === "help") {
+    if (rest.length > 1 || (rest[0] && !["init", "dev", "build"].includes(rest[0]))) {
+      throw new CliError("Usage: quickgui help [init|dev|build]");
+    }
+    return rest[0]
+      ? { command: "help", topic: rest[0] as "init" | "dev" | "build" }
+      : { command: "help" };
+  }
+  if (rest.includes("--help") || rest.includes("-h")) {
+    if (command === "init" || command === "dev" || command === "build") {
+      return { command: "help", topic: command };
+    }
+  }
+
+  if (command === "init") {
+    const parsed = parseOptions(rest, {
+      "--name": { key: "name", value: true },
+      "--identifier": { key: "identifier", value: true },
+      "--no-install": { key: "noInstall", value: false },
+    });
+    if (parsed.positionals.length > 1) throw new CliError("Usage: quickgui init [directory]");
+    const name = stringOption(parsed, "name");
+    const identifier = stringOption(parsed, "identifier");
+    return {
+      command: "init",
+      directory: parsed.positionals[0] ?? "quickgui-app",
+      install: !parsed.values.has("noInstall"),
+      ...(name ? { name } : {}),
+      ...(identifier ? { identifier } : {}),
+    };
+  }
+
+  if (command === "dev") {
+    const parsed = parseOptions(rest, {
+      "--project": { key: "project", value: true },
+      "--config": { key: "configFile", value: true },
+      "--target": { key: "target", value: true },
+      "--sign": { key: "signingIdentity", value: true },
+      "--once": { key: "once", value: false },
+      "--no-launch": { key: "noLaunch", value: false },
+    });
+    rejectPositionals(parsed, "quickgui dev");
+    const target = stringOption(parsed, "target");
+    const signingIdentity = stringOption(parsed, "signingIdentity");
+    return {
+      command: "dev",
+      project: stringOption(parsed, "project") ?? ".",
+      configFile: stringOption(parsed, "configFile") ?? "quickgui.config.ts",
+      once: parsed.values.has("once"),
+      launch: !parsed.values.has("noLaunch"),
+      ...(target ? { target: parseTarget(target) } : {}),
+      ...(signingIdentity ? { signingIdentity } : {}),
+    };
+  }
+
+  if (command === "build") {
+    const parsed = parseOptions(rest, {
+      "--project": { key: "project", value: true },
+      "--config": { key: "configFile", value: true },
+      "--target": { key: "target", value: true },
+      "--out-dir": { key: "outDir", value: true },
+      "--sign": { key: "signingIdentity", value: true },
+      "--notarize": { key: "notarizationProfile", value: true },
+    });
+    rejectPositionals(parsed, "quickgui build");
+    const target = stringOption(parsed, "target");
+    const outDir = stringOption(parsed, "outDir");
+    const signingIdentity = stringOption(parsed, "signingIdentity");
+    const notarizationProfile = stringOption(parsed, "notarizationProfile");
+    return {
+      command: "build",
+      project: stringOption(parsed, "project") ?? ".",
+      configFile: stringOption(parsed, "configFile") ?? "quickgui.config.ts",
+      ...(target ? { target: parseTarget(target) } : {}),
+      ...(outDir ? { outDir } : {}),
+      ...(signingIdentity ? { signingIdentity } : {}),
+      ...(notarizationProfile ? { notarizationProfile } : {}),
+    };
+  }
+
+  throw new CliError(`Unknown command: ${command}\nRun \`quickgui --help\` for usage.`);
+}
+
+function parseOptions(argv: string[], specs: Record<string, OptionSpec>): ParsedOptions {
+  const values = new Map<string, string | true>();
+  const positionals: string[] = [];
+  let positionalOnly = false;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index]!;
+    if (!positionalOnly && token === "--") {
+      positionalOnly = true;
+      continue;
+    }
+    if (positionalOnly || !token.startsWith("-")) {
+      positionals.push(token);
+      continue;
+    }
+    const equal = token.indexOf("=");
+    const name = equal === -1 ? token : token.slice(0, equal);
+    const inlineValue = equal === -1 ? undefined : token.slice(equal + 1);
+    const spec = specs[name];
+    if (!spec) throw new CliError(`Unknown option: ${name}`);
+    if (values.has(spec.key)) throw new CliError(`Option may only be specified once: ${name}`);
+    if (!spec.value) {
+      if (inlineValue !== undefined) throw new CliError(`Option does not take a value: ${name}`);
+      values.set(spec.key, true);
+      continue;
+    }
+    const value = inlineValue ?? argv[++index];
+    if (value === undefined || value.length === 0) {
+      throw new CliError(`Option requires a value: ${name}`);
+    }
+    if (inlineValue === undefined && specs[value]) {
+      throw new CliError(`Option requires a value: ${name}`);
+    }
+    values.set(spec.key, value);
+  }
+
+  return { values, positionals };
+}
+
+function stringOption(parsed: ParsedOptions, key: string): string | undefined {
+  const value = parsed.values.get(key);
+  return typeof value === "string" ? value : undefined;
+}
+
+function rejectPositionals(parsed: ParsedOptions, usage: string): void {
+  if (parsed.positionals.length > 0) {
+    throw new CliError(`${usage} does not accept positional arguments`);
+  }
+}