@pacaf/wizard-ux 2.0.0

package/server/routes/state.mjs

@@ -0,0 +1,88 @@
+// Routes for /api/state
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { readState, writeState, resetStateFile, getCompletedStep } from '../lib/state-bridge.mjs';
+import { TOTAL_STEPS } from '../steps/index.mjs';
+
+function pickTargetEnvUrl(state) {
+  const target = String(state.WIZARD_TARGET_ENV || 'dev').toLowerCase();
+  const map = {
+    dev: state.PP_ENV_DEV,
+    test: state.PP_ENV_TEST,
+    prod: state.PP_ENV_PROD,
+  };
+  const raw = String(map[target] || state.PP_ENV_DEV || '').trim();
+  if (!raw) return { target, environmentUrl: '' };
+  return { target, environmentUrl: raw.replace(/\/$/, '') };
+}
+
+function readPowerAppInfo(rootDir, state) {
+  const projectDir = resolve(rootDir, String(state.PROJECT_DIR || '.'));
+  const powerConfigPath = join(projectDir, 'power.config.json');
+
+  // The deployed Code App URL (apps.powerapps.com/play/...) is captured from
+  // `pac code push` stdout in Step 9 and persisted to wizard state as
+  // DEPLOYED_APP_URL. NOTE: power.config.json's `localAppUrl` is the *local*
+  // dev server URL (http://localhost:3000) — never use it for the launch CTA.
+  const deployedUrl = String(state.DEPLOYED_APP_URL || '').trim();
+
+  let appId = '';
+  if (existsSync(powerConfigPath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(powerConfigPath, 'utf-8'));
+      appId = String(parsed?.appId || '').trim();
+    } catch {
+      // ignore — appId is optional for the launch CTA
+    }
+  }
+
+  if (!deployedUrl && !appId) return null;
+
+  const { target, environmentUrl } = pickTargetEnvUrl(state);
+  return {
+    appId,
+    targetEnv: target,
+    environmentUrl,
+    launchUrl: deployedUrl,
+  };
+}
+
+export default async function stateRoutes(app, opts) {
+  const { rootDir } = opts;
+
+  app.get('/', async () => {
+    const state = readState(rootDir);
+    const completed = getCompletedStep(state);
+    const powerApp = readPowerAppInfo(rootDir, state);
+    return {
+      state,
+      completed,
+      next: Math.min(completed + 1, TOTAL_STEPS),
+      totalSteps: TOTAL_STEPS,
+      powerApp,
+    };
+  });
+
+  app.put('/', async (req, reply) => {
+    const partial = req.body || {};
+    if (typeof partial !== 'object' || Array.isArray(partial)) {
+      return reply.code(400).send({ error: 'Body must be an object' });
+    }
+    const merged = writeState(rootDir, partial);
+    return { state: merged };
+  });
+
+  app.post('/reset', async () => {
+    resetStateFile(rootDir);
+    return { ok: true };
+  });
+
+  app.post('/jump', async (req, reply) => {
+    const target = parseInt(req.body?.step, 10);
+    if (!target || target < 1 || target > TOTAL_STEPS) {
+      return reply.code(400).send({ error: `step must be 1..${TOTAL_STEPS}` });
+    }
+    const merged = writeState(rootDir, { COMPLETED_STEP: target - 1 });
+    return { state: merged };
+  });
+}

package/server/routes/steps.mjs

@@ -0,0 +1,62 @@
+// Routes for /api/steps
+import { STEPS, getStep, TOTAL_STEPS } from '../steps/index.mjs';
+import { readState, writeState, getCompletedStep } from '../lib/state-bridge.mjs';
+import { newRun, runInline } from '../lib/process-runner.mjs';
+
+export default async function stepsRoutes(app, { rootDir }) {
+  // GET /api/steps — list with status
+  app.get('/', async () => {
+    const state = readState(rootDir);
+    const completed = getCompletedStep(state);
+    return {
+      totalSteps: TOTAL_STEPS,
+      completed,
+      steps: STEPS.map((s) => ({
+        ...s.meta,
+        status: s.meta.number <= completed ? 'done' : s.meta.number === completed + 1 ? 'current' : 'pending',
+      })),
+    };
+  });
+
+  // GET /api/steps/:n/questions
+  app.get('/:n/questions', async (req, reply) => {
+    const n = parseInt(req.params.n, 10);
+    if (!n || n < 1 || n > TOTAL_STEPS) return reply.code(404).send({ error: 'Unknown step' });
+    const step = getStep(n);
+    const state = readState(rootDir);
+    const questions = await step.questions(state);
+    return {
+      meta: step.meta,
+      questions,
+      state, // include for clientside conditional rendering convenience
+    };
+  });
+
+  // POST /api/steps/:n/apply
+  app.post('/:n/apply', async (req, reply) => {
+    const n = parseInt(req.params.n, 10);
+    if (!n || n < 1 || n > TOTAL_STEPS) return reply.code(404).send({ error: 'Unknown step' });
+    const step = getStep(n);
+    if (!step.meta.canRunInBrowser) {
+      return reply.code(409).send({ error: 'Step cannot run in WizardUX' });
+    }
+    const answers = req.body?.answers || {};
+    const run = newRun();
+
+    // Kick off the apply asynchronously; client subscribes to /stream for log
+    const state = readState(rootDir);
+    queueMicrotask(async () => {
+      const outcome = await runInline(run, async (log) => {
+        const result = await step.apply(answers, state, log);
+        if (result?.stateUpdate) writeState(rootDir, result.stateUpdate);
+        if (result?.completedStep != null) {
+          writeState(rootDir, { COMPLETED_STEP: Math.max(getCompletedStep(readState(rootDir)), result.completedStep) });
+        }
+        return result;
+      });
+      void outcome;
+    });
+
+    return { runId: run.id };
+  });
+}

package/server/routes/stream.mjs

@@ -0,0 +1,49 @@
+// Routes for /api/steps/:n/stream — SSE log streaming
+import { getRun } from '../lib/process-runner.mjs';
+
+export default async function streamRoutes(app /* , opts */) {
+  app.get('/:n/stream', async (req, reply) => {
+    const runId = req.query?.runId;
+    if (!runId) return reply.code(400).send({ error: 'runId required' });
+    const run = getRun(runId);
+    if (!run) return reply.code(404).send({ error: 'Unknown runId (may have been GC\'d)' });
+
+    reply.raw.setHeader('Content-Type', 'text/event-stream');
+    reply.raw.setHeader('Cache-Control', 'no-cache');
+    reply.raw.setHeader('Connection', 'keep-alive');
+    reply.raw.flushHeaders?.();
+
+    const send = (event, data) => {
+      reply.raw.write(`event: ${event}\n`);
+      reply.raw.write(`data: ${JSON.stringify(data)}\n\n`);
+    };
+
+    // Replay buffered lines to late joiners
+    for (const line of run.lines) send('line', line);
+    if (run.deviceCode) send('deviceCode', run.deviceCode);
+    if (run.status === 'done' || run.status === 'error') {
+      send('end', { status: run.status, exitCode: run.exitCode, error: run.error });
+      reply.raw.end();
+      return reply;
+    }
+
+    const onLine = (line) => send('line', line);
+    const onDeviceCode = (dc) => send('deviceCode', dc);
+    const onEnd = () => {
+      send('end', { status: run.status, exitCode: run.exitCode, error: run.error });
+      reply.raw.end();
+    };
+
+    run.on('line', onLine);
+    run.on('deviceCode', onDeviceCode);
+    run.on('end', onEnd);
+
+    req.raw.on('close', () => {
+      run.off('line', onLine);
+      run.off('deviceCode', onDeviceCode);
+      run.off('end', onEnd);
+    });
+
+    return reply;
+  });
+}

package/server/routes/system.mjs

@@ -0,0 +1,43 @@
+// Routes for /api/system — environment & tooling diagnostics
+import { execSync, execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir, platform, release } from 'node:os';
+import { pacPath as resolvePacPath, runSafe } from '../../../wizard/lib/shell.mjs';
+
+function safeRun(cmd) {
+  try { return execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim(); }
+  catch { return null; }
+}
+
+function which(name) {
+  try {
+    const cmd = platform() === 'win32' ? 'where' : 'which';
+    execFileSync(cmd, [name], { stdio: 'ignore' });
+    return true;
+  } catch { return false; }
+}
+
+function pacVersion() {
+  const ext = platform() === 'win32' ? '.exe' : '';
+  const dotnetTool = join(homedir(), '.dotnet', 'tools', `pac${ext}`);
+  const pacPath = existsSync(dotnetTool) ? dotnetTool : resolvePacPath();
+  if (!pacPath) return null;
+  const out = runSafe(pacPath, []);
+  const m = out?.match(/Version:\s*(\S+)/i);
+  return m ? m[1] : (out ? 'unknown' : null);
+}
+
+export default async function systemRoutes(app, { rootDir }) {
+  app.get('/', async () => ({
+    os: { platform: platform(), release: release() },
+    node: process.version,
+    git: safeRun('git --version')?.replace('git version ', '') || null,
+    dotnet: safeRun('dotnet --version'),
+    pac: pacVersion(),
+    op: which('op'),
+    rootDir,
+    branch: safeRun(`git -C "${rootDir}" rev-parse --abbrev-ref HEAD`) || null,
+    repoIsClean: safeRun(`git -C "${rootDir}" status --porcelain`) === '',
+  }));
+}

package/server/steps/01-prerequisites.mjs

@@ -0,0 +1,127 @@
+// Step 1 — Prerequisites. Read-only checks, no questions.
+import { platform } from 'node:os';
+import { execFileSync, execSync } from 'node:child_process';
+import { pacPath, runSafe } from '../../../wizard/lib/shell.mjs';
+
+function hasCommand(name) {
+  try {
+    const cmd = platform() === 'win32' ? 'where' : 'which';
+    execFileSync(cmd, [name], { stdio: 'ignore' });
+    return true;
+  } catch { return false; }
+}
+
+function tryRun(cmd) {
+  try { return execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim(); }
+  catch { return null; }
+}
+
+export default {
+  meta: {
+    number: 1,
+    title: 'Prerequisites',
+    description: 'Verify Node, Git, .NET SDK, PAC CLI, Python 3, and optional tools are present.',
+    canRunInBrowser: true,
+    readOnly: true,
+  },
+
+  questions() { return []; },
+
+  async apply(_answers, _state, log) {
+    const checks = [];
+    let allOk = true;
+    let hasOp = false;
+
+    // Node
+    if (hasCommand('node')) {
+      const ver = tryRun('node --version') || '';
+      const major = parseInt(ver.replace(/^v/, ''), 10);
+      const ok = major >= 20;
+      checks.push({ name: 'Node.js', ok, value: ver, hint: ok ? null : 'Version 20+ required (https://nodejs.org/)' });
+      if (ok) log.ok(`Node.js ${ver}`); else { log.fail(`Node.js ${ver} — version 20+ required`); allOk = false; }
+    } else {
+      checks.push({ name: 'Node.js', ok: false, value: null, hint: 'Not installed (https://nodejs.org/)' });
+      log.fail('Node.js — not found'); allOk = false;
+    }
+
+    // Git
+    if (hasCommand('git')) {
+      const ver = tryRun('git --version')?.replace('git version ', '') || '';
+      checks.push({ name: 'Git', ok: true, value: ver, hint: null });
+      log.ok(`Git ${ver}`);
+    } else {
+      checks.push({ name: 'Git', ok: false, value: null, hint: 'Not installed (https://git-scm.com/)' });
+      log.fail('Git — not found'); allOk = false;
+    }
+
+    // .NET
+    if (hasCommand('dotnet')) {
+      const ver = tryRun('dotnet --version') || '';
+      checks.push({ name: '.NET SDK', ok: true, value: ver, hint: null });
+      log.ok(`.NET SDK ${ver}`);
+    } else {
+      checks.push({ name: '.NET SDK', ok: false, value: null, hint: 'Required for PAC CLI (https://dotnet.microsoft.com/download)' });
+      log.fail('.NET SDK — not found'); allOk = false;
+    }
+
+    // PAC CLI
+    const pac = pacPath();
+    if (pac) {
+      const header = runSafe(pac, []) || '';
+      const m = header.match(/Version:\s*(\S+)/i);
+      const pacVer = m ? m[1] : 'unknown';
+      const bad = pacVer.includes('2.3.2');
+      checks.push({ name: 'PAC CLI', ok: !bad, value: pacVer, hint: bad ? 'Version 2.3.2 has a known bug — install 2.2.1 instead' : null });
+      if (bad) { log.fail(`PAC CLI ${pacVer} — known-bad version`); allOk = false; }
+      else log.ok(`PAC CLI ${pacVer}`);
+    } else {
+      checks.push({ name: 'PAC CLI', ok: false, value: null, hint: 'Run: dotnet tool install -g Microsoft.PowerApps.CLI.Tool' });
+      log.fail('PAC CLI — not found'); allOk = false;
+    }
+
+    // 1Password CLI (optional)
+    if (hasCommand('op')) {
+      hasOp = true;
+      checks.push({ name: '1Password CLI', ok: true, value: 'available', hint: null, optional: true });
+      log.ok('1Password CLI available');
+    } else {
+      checks.push({ name: '1Password CLI', ok: false, value: null, hint: 'Optional — speeds up secret handling', optional: true });
+      log.info('1Password CLI not found (optional)');
+    }
+
+    // Python 3 (used by Dataverse-skills plugin)
+    let pythonCmd = null;
+    if (hasCommand('python3')) pythonCmd = 'python3';
+    else if (hasCommand('python')) pythonCmd = 'python';
+
+    if (pythonCmd) {
+      const pyVer = tryRun(`${pythonCmd} --version`)?.replace('Python ', '') || '';
+      const pyMajor = parseInt(pyVer, 10);
+      if (pyMajor >= 3) {
+        checks.push({ name: 'Python', ok: true, value: pyVer, hint: null });
+        log.ok(`Python ${pyVer}`);
+      } else {
+        checks.push({ name: 'Python', ok: false, value: pyVer, hint: 'Python 3+ required for Dataverse-skills plugin (https://www.python.org/downloads/)' });
+        log.warn(`Python ${pyVer} — Python 3+ required for Dataverse-skills plugin`);
+        log.info('  → Install Python 3: https://www.python.org/downloads/');
+        log.info('  → Then re-run this step to verify');
+        pythonCmd = null;
+      }
+    } else {
+      checks.push({ name: 'Python', ok: false, value: null, hint: 'Required for Dataverse-skills plugin (https://www.python.org/downloads/)' });
+      log.warn('Python 3 — not found (required for Dataverse-skills plugin)');
+      log.info('  → Install Python 3: https://www.python.org/downloads/');
+      log.info('  → Then re-run this step to verify');
+    }
+
+    // Note: The Dataverse-skills plugin manages its own Python SDK installation
+    // via the dv-connect skill. No separate pip install needed here.
+
+    return {
+      stateUpdate: { HAS_OP: hasOp, PYTHON_CMD: pythonCmd },
+      result: { allOk, checks },
+      // Mark step complete only if no required tool is missing
+      completedStep: allOk ? 1 : null,
+    };
+  },
+};

package/server/steps/02-project-and-env.mjs

@@ -0,0 +1,108 @@
+// Step 2 — Project name + environment URLs.
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const VALIDATE_PATH = resolve(__dirname, '..', '..', '..', 'wizard', 'lib', 'validate.mjs');
+const { isValidDataverseUrl, normalizeDataverseUrl } = await import(pathToFileURL(VALIDATE_PATH).href);
+
+const URL_HINT = 'Format: https://org-name.crm.dynamics.com (the wizard adds https:// for you if you paste it without).';
+
+export default {
+  meta: {
+    number: 2,
+    title: 'Project & Environment',
+    description: 'Name your app and point the wizard at your Dev (and optionally Test/Prod) Power Platform environments.',
+    canRunInBrowser: true,
+  },
+
+  questions(state) {
+    return [
+      {
+        id: 'APP_NAME',
+        type: 'text',
+        label: 'App name',
+        help: 'A human-readable display name. e.g. "Project Tracker", "My Brain".',
+        required: true,
+        defaultValue: state.APP_NAME || '',
+      },
+      {
+        id: 'PP_ENV_DEV',
+        type: 'url',
+        label: 'Dev environment URL',
+        help: 'The URL of your Power Platform development environment. Paste it straight from PPAC — with or without https://. ' + URL_HINT,
+        why: [
+          "If you haven't created one yet:",
+          '1. Open https://admin.powerplatform.microsoft.com',
+          '2. Environments → + New',
+          '3. Type: Developer or Sandbox · toggle "Add Dataverse" YES',
+          '4. Save, wait for provisioning, then copy the Environment URL.',
+        ].join('\n'),
+        required: true,
+        defaultValue: state.PP_ENV_DEV || '',
+        validatePattern: 'dataverseUrl',
+      },
+      {
+        id: 'PP_ENV_TEST',
+        type: 'url',
+        label: 'Test environment URL',
+        help: 'Optional. Leave blank if you do not have a separate Test environment yet.',
+        required: false,
+        defaultValue: state.PP_ENV_TEST || '',
+        validatePattern: 'dataverseUrl',
+      },
+      {
+        id: 'PP_ENV_PROD',
+        type: 'url',
+        label: 'Prod environment URL',
+        help: 'Optional. Leave blank if you do not have a Prod environment yet.',
+        required: false,
+        defaultValue: state.PP_ENV_PROD || '',
+        validatePattern: 'dataverseUrl',
+      },
+    ];
+  },
+
+  async apply(answers, _state, log) {
+    const errors = {};
+    const norm = (s) => normalizeDataverseUrl(s);
+
+    const appName = (answers.APP_NAME || '').trim();
+    if (!appName) errors.APP_NAME = 'Required';
+
+    const dev = norm(answers.PP_ENV_DEV);
+    if (!dev) errors.PP_ENV_DEV = 'Required';
+    else if (!isValidDataverseUrl(dev) && !isValidDataverseUrl(dev + '/')) errors.PP_ENV_DEV = URL_HINT;
+
+    const test = norm(answers.PP_ENV_TEST);
+    if (test && !isValidDataverseUrl(test) && !isValidDataverseUrl(test + '/')) {
+      log.warn(`Test URL "${test}" doesn't look standard, saving anyway.`);
+    }
+
+    const prod = norm(answers.PP_ENV_PROD);
+    if (prod && !isValidDataverseUrl(prod) && !isValidDataverseUrl(prod + '/')) {
+      log.warn(`Prod URL "${prod}" doesn't look standard, saving anyway.`);
+    }
+
+    if (Object.keys(errors).length > 0) {
+      const msg = Object.entries(errors).map(([k, v]) => `${k}: ${v}`).join('; ');
+      throw new Error(`Validation failed — ${msg}`);
+    }
+
+    log.ok(`App name: ${appName}`);
+    log.ok(`Dev env: ${dev}`);
+    if (test) log.ok(`Test env: ${test}`); else log.info('Test env: (skipped)');
+    if (prod) log.ok(`Prod env: ${prod}`); else log.info('Prod env: (skipped)');
+
+    return {
+      stateUpdate: {
+        APP_NAME: appName,
+        PP_ENV_DEV: dev,
+        PP_ENV_TEST: test,
+        PP_ENV_PROD: prod,
+        WIZARD_TARGET_ENV: 'dev',
+      },
+      completedStep: 2,
+    };
+  },
+};