create-middag-ui 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,91 @@
+# create-middag-ui
+
+Bootstrap a [MIDDAG React UI](https://github.com/middag-io/middag-react) layer in your Moodle or WordPress plugin.
+
+## Usage
+
+```bash
+npx create-middag-ui
+```
+
+Or specify a custom directory:
+
+```bash
+npx create-middag-ui mydir
+```
+
+Run from your plugin project root. The wizard:
+
+1. **Auto-detects your host** — finds `version.php` (Moodle) or `wp-config.php` (WordPress)
+2. **Asks for target directory** — default `ui/`, or pass as CLI argument
+3. **Configures registry** — GitHub Packages (with source maps) or npm public (no auth needed)
+4. **Scaffolds everything** — config files, demo components, mock environment
+5. **Installs dependencies** — runs `npm install` automatically with progress feedback
+
+Then start developing:
+
+```bash
+cd ui
+npm run dev:mock
+```
+
+Your mock opens at `http://localhost:5174` (Moodle), `5175` (WordPress), or `5176` (Custom).
+
+## What it creates
+
+```
+ui/
+  package.json              # Dependencies and scripts
+  tsconfig.json             # TypeScript config with path aliases
+  vite.mock.config.ts       # Vite dev server config for mock build
+  src/
+    blocks/
+      hello-block.tsx       # Custom block example (rename me!)
+    components/
+      greeting.tsx          # Standalone component example (rename me!)
+    contracts.ts            # PageContract type re-export
+  mock/
+    index.html              # HTML entry point
+    main.tsx                # React entry with registerDefaults() + ContractPage
+    hello-contract.ts       # Example PageContract (metric card + data table)
+    tailwind.css            # Tailwind CSS import
+```
+
+## Dual Registry
+
+`@middag-io/react` is available from two registries:
+
+### npm public (default, no auth)
+
+Choose "No" when asked about GitHub access. Dependencies install from the public npm registry with zero configuration.
+
+### GitHub Packages (with source maps)
+
+Choose "Yes" when asked about GitHub access. The wizard will:
+
+1. Ask for your GitHub Personal Access Token
+2. Validate the token against GitHub Packages
+3. Save the registry + token to `~/.npmrc` (global, not project-local)
+
+Create a token at [github.com/settings/tokens](https://github.com/settings/tokens) with the `read:packages` scope.
+
+## After setup
+
+Once `@middag-io/react` is installed, more commands become available from inside your UI directory:
+
+```bash
+npx @middag-io/react doctor        # Validate project setup
+npx @middag-io/react dev            # Start mock dev server
+npx @middag-io/react add-block <t>  # Scaffold a new block type
+npx @middag-io/react upgrade        # Check for updates
+```
+
+## Documentation
+
+- **[Live Demo](https://middag-react-mock.pages.dev)** — 24 screens showing all block types
+- **[Full Documentation](https://docs.middag.io)** — Getting started, host guides, API reference
+- **[GitHub](https://github.com/middag-io/middag-react)** — Source code and issues
+
+## License
+
+MIT

package/cli.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/* global console, process */
+
+/**
+ * create-middag-ui — Bootstrap a MIDDAG React UI layer.
+ *
+ * Published on public npm so `npx create-middag-ui` works without
+ * GitHub Packages authentication. This package handles:
+ *   1. Host detection (Moodle / WordPress / Custom)
+ *   2. Directory selection (default: ui/, or CLI arg)
+ *   3. GitHub access check (dual registry: GitHub Packages or npm public)
+ *   4. Directory + config scaffolding
+ *   5. Demo files (custom block, standalone component, type re-export)
+ *   6. Mock files (hello-contract, entry point, HTML, CSS)
+ *   7. npm install with spinner
+ *   8. Summary with next steps
+ *
+ * After init, more CLI commands are available via:
+ *   npx @middag-io/react <command>
+ */
+
+import { join } from "node:path";
+import { detectHost, HOSTS } from "./lib/detect.js";
+import { ask, select, confirm } from "./lib/prompts.js";
+import { runTokenFlow } from "./lib/auth.js";
+import {
+  createTargetDir,
+  scaffoldPackageJson,
+  scaffoldTsconfig,
+  scaffoldViteConfig,
+  scaffoldDemoFiles,
+  scaffoldMockFiles,
+} from "./lib/scaffold.js";
+import { runNpmInstall } from "./lib/install.js";
+import { log, success, heading, blank, info } from "./lib/ui.js";
+
+const TOTAL_STEPS = 10;
+const cwd = process.cwd();
+const startTime = Date.now();
+
+blank();
+log("Initializing MIDDAG React UI...\n");
+
+// ── Step 1: Detect host ──────────────────────────────────────────────────
+
+heading(1, TOTAL_STEPS, "Detecting host platform");
+
+let hostKey = detectHost(cwd);
+if (hostKey) {
+  success(`Detected: ${HOSTS[hostKey].name} (found ${HOSTS[hostKey].detect})`);
+} else {
+  info("Could not auto-detect host platform.");
+  hostKey = await select("Select platform", [
+    { label: "Moodle", value: "moodle" },
+    { label: "WordPress", value: "wordpress" },
+    { label: "Custom / Other", value: "custom" },
+  ]);
+  success(`Selected: ${HOSTS[hostKey].name}`);
+}
+
+const host = HOSTS[hostKey];
+
+// ── Step 2: Ask directory ────────────────────────────────────────────────
+
+heading(2, TOTAL_STEPS, "Target directory");
+
+const cliArg = process.argv[2];
+let dirName;
+
+if (cliArg && !cliArg.startsWith("-")) {
+  dirName = cliArg;
+  success(`Using directory from argument: ${dirName}/`);
+} else {
+  const answer = await ask(`  Directory name (default: ui): `);
+  dirName = answer || "ui";
+  success(`Target: ${dirName}/`);
+}
+
+const targetDir = join(cwd, dirName);
+
+// ── Step 3: Ask GitHub access ────────────────────────────────────────────
+
+heading(3, TOTAL_STEPS, "Registry configuration");
+
+info("@middag-io/react can be installed from:");
+info("  a) GitHub Packages (with source maps, requires token)");
+info("  b) npm public registry (compiled only, no auth needed)");
+blank();
+
+const hasGitHubAccess = await confirm("Do you have GitHub access to middag-io?", false);
+
+let registryPath = "public";
+if (hasGitHubAccess) {
+  registryPath = await runTokenFlow();
+} else {
+  success("Using npm public registry (no authentication needed)");
+}
+
+// ── Step 4: Create directory ─────────────────────────────────────────────
+
+heading(4, TOTAL_STEPS, "Creating directory");
+
+const dirCreated = createTargetDir(targetDir);
+if (!dirCreated) {
+  process.exit(1);
+}
+
+// ── Step 5: Scaffold config files ────────────────────────────────────────
+
+heading(5, TOTAL_STEPS, "Scaffolding config files");
+
+scaffoldPackageJson(targetDir, host, cwd);
+scaffoldTsconfig(targetDir);
+scaffoldViteConfig(targetDir, host);
+
+// ── Step 6: Scaffold ~/.npmrc (GitHub path only) ─────────────────────────
+
+heading(6, TOTAL_STEPS, "Registry setup");
+
+if (registryPath === "github") {
+  success("GitHub Packages registry configured in ~/.npmrc (global)");
+  info("Token was saved during authentication step");
+} else {
+  success("No registry config needed (using npm public)");
+}
+
+// ── Step 7: Scaffold demo files in src/ ──────────────────────────────────
+
+heading(7, TOTAL_STEPS, "Creating demo files");
+
+scaffoldDemoFiles(targetDir);
+
+// ── Step 8: Scaffold mock files ──────────────────────────────────────────
+
+heading(8, TOTAL_STEPS, "Creating mock environment");
+
+scaffoldMockFiles(targetDir);
+
+// ── Step 9: npm install ──────────────────────────────────────────────────
+
+heading(9, TOTAL_STEPS, "Installing dependencies");
+
+info("This may take a minute...");
+blank();
+
+const installOk = await runNpmInstall(targetDir, registryPath);
+
+// ── Step 10: Summary ─────────────────────────────────────────────────────
+
+heading(10, TOTAL_STEPS, "Done!");
+
+const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+blank();
+
+if (installOk) {
+  log(`MIDDAG React UI ready in ${dirName}/ (${elapsed}s)\n`);
+  console.log("  Start developing:");
+  console.log(`    cd ${dirName}`);
+  console.log(`    npm run dev:mock        \u2192 mock server at http://localhost:${host.port}`);
+} else {
+  log(`Scaffold complete in ${dirName}/ (${elapsed}s) \u2014 install failed\n`);
+  console.log("  To retry install:");
+  console.log(`    cd ${dirName}`);
+  console.log("    npm install");
+  console.log(`    npm run dev:mock        \u2192 mock server at http://localhost:${host.port}`);
+}
+
+blank();
+console.log("  Your scaffold includes:");
+console.log("    src/blocks/hello-block.tsx    \u2190 custom block example (rename me!)");
+console.log("    src/components/greeting.tsx   \u2190 standalone component (rename me!)");
+console.log("    src/contracts.ts              \u2190 PageContract type re-export");
+console.log("    mock/hello-contract.ts        \u2190 example PageContract with data");
+
+blank();
+console.log(`  Integrate with your ${host.name} plugin:`);
+console.log("    1. Import { ContractPage } from '@middag-io/react'");
+console.log("    2. Pass your Inertia page props as the contract");
+console.log("    3. See: https://docs.middag.io/getting-started");
+
+blank();
+console.log("  More commands (after install):");
+console.log("    npx @middag-io/react doctor     \u2192 validate setup");
+console.log("    npx @middag-io/react add-block  \u2192 scaffold new block type");
+console.log("    npx @middag-io/react upgrade     \u2192 check for updates");
+
+blank();
+console.log("  Docs: https://docs.middag.io");
+blank();

package/lib/auth.js

@@ -0,0 +1,210 @@
+/* global console, process */
+/**
+ * auth.js — GitHub token flow (ask, validate, save to ~/.npmrc).
+ *
+ * Token is stored in ~/.npmrc (global), never in project-local .npmrc.
+ * Two lines are written:
+ *   @middag-io:registry=https://npm.pkg.github.com
+ *   //npm.pkg.github.com/:_authToken=TOKEN
+ */
+
+import { existsSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { askSecret, confirm } from "./prompts.js";
+import { success, warn, error, info, createSpinner } from "./ui.js";
+
+const REGISTRY_URL = "https://npm.pkg.github.com";
+const SCOPE_LINE = `@middag-io:registry=${REGISTRY_URL}`;
+const TOKEN_PREFIX = `//npm.pkg.github.com/:_authToken=`;
+
+/**
+ * Check if ~/.npmrc already has a valid GitHub Packages token for @middag-io.
+ *
+ * @returns {{ hasScope: boolean, hasToken: boolean }}
+ */
+export function checkExistingAuth() {
+  const npmrcPath = join(homedir(), ".npmrc");
+  if (!existsSync(npmrcPath)) {
+    return { hasScope: false, hasToken: false };
+  }
+
+  try {
+    const content = readFileSync(npmrcPath, "utf-8");
+    const hasScope = content.includes(SCOPE_LINE);
+    const hasToken = content.includes(TOKEN_PREFIX);
+    return { hasScope, hasToken };
+  } catch {
+    return { hasScope: false, hasToken: false };
+  }
+}
+
+/**
+ * Validate a GitHub token by running `npm whoami` against GitHub Packages.
+ *
+ * @param {string} token - GitHub personal access token
+ * @returns {{ valid: boolean, username: string|null }}
+ */
+export function validateToken(token) {
+  try {
+    const result = spawnSync(
+      "npm",
+      ["whoami", `--registry=${REGISTRY_URL}`],
+      {
+        env: {
+          ...process.env,
+          // Temporarily set the token for this check
+          npm_config__npm_pkg_github_com__authToken: token,
+        },
+        timeout: 15000,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+      },
+    );
+
+    if (result.status === 0 && result.stdout) {
+      return { valid: true, username: result.stdout.trim() };
+    }
+    return { valid: false, username: null };
+  } catch {
+    return { valid: false, username: null };
+  }
+}
+
+/**
+ * Save scope + token to ~/.npmrc (global).
+ * Appends only the lines that are missing.
+ *
+ * @param {string} token - GitHub personal access token
+ */
+export function saveTokenToGlobalNpmrc(token) {
+  const npmrcPath = join(homedir(), ".npmrc");
+  let content = "";
+
+  if (existsSync(npmrcPath)) {
+    try {
+      content = readFileSync(npmrcPath, "utf-8");
+    } catch (err) {
+      throw new Error(`Cannot read ~/.npmrc: ${err.message}`, { cause: err });
+    }
+  }
+
+  // If an existing token line exists, replace it in-place
+  if (content.includes(TOKEN_PREFIX)) {
+    const updated = content.replace(
+      new RegExp(`${TOKEN_PREFIX.replace(/[/]/g, "\\/")}.*`, "g"),
+      `${TOKEN_PREFIX}${token}`,
+    );
+    try {
+      writeFileSync(npmrcPath, updated);
+    } catch (err) {
+      throw new Error(`Cannot write ~/.npmrc: ${err.message}`, { cause: err });
+    }
+    // Still need to add scope if missing
+    if (!content.includes(SCOPE_LINE)) {
+      try {
+        appendFileSync(npmrcPath, `\n${SCOPE_LINE}\n`);
+      } catch (err) {
+        throw new Error(`Cannot append to ~/.npmrc: ${err.message}`, { cause: err });
+      }
+    }
+    return;
+  }
+
+  // No existing token — append new lines
+  const lines = [];
+  if (!content.includes(SCOPE_LINE)) {
+    lines.push(SCOPE_LINE);
+  }
+  lines.push(`${TOKEN_PREFIX}${token}`);
+
+  const prefix = content && !content.endsWith("\n") ? "\n" : "";
+  try {
+    appendFileSync(npmrcPath, `${prefix}${lines.join("\n")}\n`);
+  } catch (err) {
+    throw new Error(`Cannot write to ~/.npmrc: ${err.message}`, { cause: err });
+  }
+}
+
+/**
+ * Interactive GitHub token flow.
+ *
+ * 1. Ask for token (masked input)
+ * 2. Validate with npm whoami
+ * 3. Save to ~/.npmrc if valid
+ * 4. If invalid, offer fallback to npm publico
+ *
+ * @returns {Promise<'github'|'public'>} Which registry path was chosen
+ */
+export async function runTokenFlow() {
+  // Check if already configured
+  const existing = checkExistingAuth();
+  if (existing.hasScope && existing.hasToken) {
+    const spinner = createSpinner("Checking existing GitHub Packages auth...");
+    const result = spawnSync(
+      "npm",
+      ["whoami", `--registry=${REGISTRY_URL}`],
+      {
+        timeout: 15000,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+      },
+    );
+    spinner.stop();
+
+    if (result.status === 0 && result.stdout) {
+      success(`Already authenticated as ${result.stdout.trim()} on GitHub Packages`);
+      return "github";
+    }
+    warn("Existing GitHub Packages token is invalid or expired");
+  }
+
+  console.log("");
+  info("Create a GitHub Personal Access Token at:");
+  info("  https://github.com/settings/tokens");
+  info("Required scope: read:packages");
+  console.log("");
+
+  const token = await askSecret("  GitHub token: ");
+
+  if (!token) {
+    warn("No token provided");
+    const useFallback = await confirm("Continue without token? (uses npm public registry)", true);
+    if (useFallback) {
+      return "public";
+    }
+    process.exit(1);
+  }
+
+  // Validate
+  const spinner = createSpinner("Validating token...");
+  const result = validateToken(token);
+  if (result.valid) {
+    spinner.stop(`Token valid \u2014 authenticated as ${result.username}`);
+  } else {
+    spinner.fail("Token invalid or missing read:packages scope");
+    console.log("");
+    info("Make sure your token has the read:packages scope.");
+    info("Create one at: https://github.com/settings/tokens");
+    console.log("");
+    const useFallback = await confirm("Continue without token? (uses npm public registry)", true);
+    if (useFallback) {
+      return "public";
+    }
+    process.exit(1);
+  }
+
+  // Save to ~/.npmrc
+  try {
+    saveTokenToGlobalNpmrc(token);
+    success("Saved registry + token to ~/.npmrc (global)");
+  } catch (err) {
+    error(`Failed to save token: ${err.message}`);
+    warn("You can add it manually to ~/.npmrc:");
+    info(`  ${SCOPE_LINE}`);
+    info(`  ${TOKEN_PREFIX}<your-token>`);
+  }
+
+  return "github";
+}

package/lib/detect.js

@@ -0,0 +1,29 @@
+/**
+ * detect.js — Host detection (Moodle / WordPress / Custom).
+ *
+ * Checks for marker files in the working directory.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+export const HOSTS = {
+  moodle: { name: "Moodle", detect: "version.php", port: 5174 },
+  wordpress: { name: "WordPress", detect: "wp-config.php", port: 5175 },
+  custom: { name: "Custom", detect: null, port: 5176 },
+};
+
+/**
+ * Detect host platform by checking for marker files.
+ *
+ * @param {string} cwd - Directory to check
+ * @returns {string|null} Host key ('moodle', 'wordpress') or null
+ */
+export function detectHost(cwd) {
+  for (const [key, host] of Object.entries(HOSTS)) {
+    if (host.detect && existsSync(join(cwd, host.detect))) {
+      return key;
+    }
+  }
+  return null;
+}

package/lib/install.js

@@ -0,0 +1,92 @@
+/* global console, process */
+/**
+ * install.js — npm install runner with spinner.
+ *
+ * Spawns `npm install` in the target directory, shows a spinner,
+ * and surfaces errors clearly if it fails.
+ */
+
+import { spawn } from "node:child_process";
+import { createSpinner, error, warn, info } from "./ui.js";
+
+/**
+ * Run `npm install` in the target directory.
+ *
+ * Shows a spinner while running. On failure, prints the npm error
+ * output and suggests troubleshooting steps.
+ *
+ * @param {string} targetDir - Absolute path to the directory
+ * @param {'github'|'public'} registryPath - Which registry was chosen
+ * @returns {Promise<boolean>} true if install succeeded
+ */
+export async function runNpmInstall(targetDir, registryPath) {
+  const registryLabel =
+    registryPath === "github" ? "GitHub Packages" : "npm public registry";
+
+  const spinner = createSpinner(
+    `Installing dependencies from ${registryLabel}...`,
+  );
+
+  return new Promise((resolve) => {
+    const child = spawn("npm", ["install"], {
+      cwd: targetDir,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: process.env,
+    });
+
+    let stderr = "";
+
+    child.stdout.on("data", () => {
+      // consume stdout silently
+    });
+
+    child.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+
+    child.on("error", (err) => {
+      spinner.fail("npm install failed to start");
+      error(`Could not run npm: ${err.message}`);
+      info("Make sure npm is installed and in your PATH.");
+      resolve(false);
+    });
+
+    child.on("close", (code) => {
+      if (code === 0) {
+        spinner.stop("Dependencies installed");
+        resolve(true);
+      } else {
+        spinner.fail("npm install failed");
+
+        // Show the npm error, trimmed
+        if (stderr) {
+          const lines = stderr.trim().split("\n");
+          // Show last 15 lines max (most relevant npm errors are at the end)
+          const relevant = lines.slice(-15);
+          console.log("");
+          for (const line of relevant) {
+            console.log(`    ${line}`);
+          }
+          console.log("");
+        }
+
+        // Suggest troubleshooting based on path
+        if (registryPath === "github") {
+          warn("Troubleshooting:");
+          info("  1. Check your GitHub token has read:packages scope");
+          info("  2. Verify token in ~/.npmrc:");
+          info("     cat ~/.npmrc | grep github");
+          info("  3. Try: npm whoami --registry=https://npm.pkg.github.com");
+          info("  4. Or re-run: npx create-middag-ui (choose 'No' for GitHub access)");
+        } else {
+          warn("Troubleshooting:");
+          info("  1. Check your internet connection");
+          info("  2. Try running manually: cd " + targetDir + " && npm install");
+          info("  3. Check npm registry: npm config get registry");
+        }
+
+        resolve(false);
+      }
+    });
+  });
+}