@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-coded-apps/assets/scripts/dashboards/flows/upgrade.mjs

@@ -0,0 +1,73 @@
+// Use-case flow: project-wide UPGRADE — refresh the disposable scaffold framework
+// over a project, migrate intent, regenerate every widget from durable state, and
+// re-validate. Extracted from build-dashboard.mjs; shared primitives are imported
+// back from it (benign cycle — used only at call time).
+
+import { execSync } from 'child_process'
+import { join, dirname } from 'path'
+import { existsSync, readFileSync } from 'fs'
+import { runIntentMigrations, runPrewarm, buildVersions, checkSdkVersion, readScaffoldVersion } from '../lifecycle.mjs'
+import {
+  log, fail, emit, writeAtomic, setWidgetsDir, assertScaffoldExtracted,
+  rebuildAllWidgets, generateDashboardFiles, injectAppRoutes, collectKeyedViews,
+  runMetricsTypecheck, STATE_SCHEMA_VERSION,
+} from '../build-dashboard.mjs'
+
+/**
+ * Upgrade an existing dashboard to the current scaffold: refresh the disposable
+ * framework, migrate intent.json, regenerate widgets/views from durable intent +
+ * on-disk metric modules, re-validate, and re-stamp versions. The durable set
+ * (intent.json, src/metrics, .dashboard, and uipath.json — the SDK config) is
+ * preserved. The framework refresh extracts the starter-kit archive with the OS tar (see CAPABILITY.md).
+ * @param {string} P  resolved project dir
+ * @param {object} state  parsed state.json
+ * @param {string} intentPath  edit-intent path (for the migrations dir + retry signal)
+ */
+export async function runUpgrade(P, state, intentPath) {
+  // Best-effort dirty-tree warning — upgrade regenerates disposable files.
+  try {
+    const dirty = execSync(`git -C "${P}" status --porcelain`, { stdio: 'pipe' }).toString().trim()
+    if (dirty) log('⚠ Project has uncommitted changes — upgrade regenerates disposable files (your intent.json + src/metrics are preserved).')
+  } catch { /* not a git repo — nothing to check */ }
+
+  // 1. Refresh the disposable scaffold framework: the agent re-extracts the
+  //    latest starter-kit archive over the project before --upgrade (preserving
+  //    src/metrics, intent.json, and uipath.json — the SDK config the plugin
+  //    injects). Verify the fresh kit is present and point at its templates.
+  assertScaffoldExtracted(P)
+  setWidgetsDir(join(P, '_gen', 'widgets'))
+
+  // 2. Migrate intent.json if present (no-op today — empty registry).
+  const intentJsonPath = join(P, 'intent.json')
+  if (existsSync(intentJsonPath)) {
+    const migrated = await runIntentMigrations(
+      JSON.parse(readFileSync(intentJsonPath, 'utf8')),
+      join(dirname(intentPath), 'migrations'),
+    )
+    writeAtomic(intentJsonPath, JSON.stringify(migrated, null, 2))
+  }
+
+  // 3. Ensure deps, then regenerate from durable intent + on-disk metric modules.
+  const LOCK_SIGNAL = join(P, 'node_modules', '.package-lock.json')
+  if (!existsSync(LOCK_SIGNAL)) { log('⚙ Installing dependencies…'); await runPrewarm(P) }
+  rebuildAllWidgets(P, state, state.timeRange ?? '30d')
+  const widgetMeta = Object.entries(state.widgets ?? {}).map(([name, info]) => ({ componentName: name, template: info.template ?? 'ranked-table' }))
+  generateDashboardFiles(P, widgetMeta, state.app?.name ?? 'Dashboard', state.app?.description ?? '')
+  injectAppRoutes(
+    P,
+    Object.keys(state.widgets ?? {}).filter(n => existsSync(join(P, 'src', 'dashboard', 'views', `${n}View.tsx`))),
+    collectKeyedViews(P, state),
+  )
+
+  // 4. Validate: Stage A (metric modules in isolation) then the full app.
+  const stageA = runMetricsTypecheck(P)
+  if (!stageA.ok) { emit('METRICS_RETRY', { files: stageA.files, errors: stageA.errors, intentPath }); process.exit(2) }
+  try { execSync('npx tsc --noEmit', { cwd: P, stdio: 'pipe' }) }
+  catch (e) { emit('TSC_FAIL', { errors: (e.stdout?.toString() || '').slice(0, 1000) }); fail('Upgrade produced TypeScript errors') }
+
+  // 5. Re-stamp + persist.
+  state.schemaVersion = STATE_SCHEMA_VERSION
+  state.versions = buildVersions(checkSdkVersion(P).version, readScaffoldVersion(P))
+  writeAtomic(join(P, '.dashboard', 'state.json'), JSON.stringify(state, null, 2))
+  emit('UPGRADE_DONE', { to: readScaffoldVersion(P), widgets: Object.keys(state.widgets ?? {}) })
+}

package/skills/uipath-coded-apps/assets/scripts/dashboards/lifecycle.mjs

@@ -0,0 +1,207 @@
+// Project-lifecycle utilities for the dashboard build pipeline — versioning,
+// dependency pre-warm, SDK-version check, and dev-server teardown. Extracted from
+// build-dashboard.mjs to keep that file focused on generation + orchestration.
+//
+// These functions depend only on small primitives (emit/log/writeAtomic) and a few
+// constants from build-dashboard.mjs; they never call the widget/view generators, so
+// there is no tight coupling. (The import from build-dashboard.mjs forms a benign
+// runtime cycle — every cross-reference is used inside a function body, never at
+// module-evaluation time, so the live bindings are resolved by call time.)
+
+import { readFileSync, existsSync, unlinkSync } from 'fs'
+import { join } from 'path'
+import { pathToFileURL } from 'url'
+import { execSync } from 'child_process'
+import { createConnection } from 'net'
+import { emit, log, writeAtomic, SKILL_VERSION, INTENT_SCHEMA_VERSION, MIN_SDK_VERSION, DASHBOARD_PORT } from './build-dashboard.mjs'
+
+/**
+ * Read the scaffold version from the EXTRACTED starter kit — `_gen/starter-kit.json`
+ * inside the project. The version ships INSIDE the archive (single fixture artifact);
+ * there is no separate `.version` file. Returns '0.0.0' if the marker is absent.
+ * @param {string} projectDir
+ */
+export function readScaffoldVersion(projectDir) {
+  try {
+    return JSON.parse(readFileSync(join(projectDir, '_gen', 'starter-kit.json'), 'utf8')).version || '0.0.0'
+  } catch { return '0.0.0' }
+}
+
+/**
+ * The version block stamped into state.json so a dashboard knows what it was
+ * built against (drives offer-on-detect upgrade + future migrations).
+ * @param {string|null} [sdkVersion]
+ * @param {string} [scaffoldVersion] - the extracted scaffold's version (readScaffoldVersion(projectDir))
+ */
+export function buildVersions(sdkVersion = null, scaffoldVersion = '0.0.0') {
+  return { skill: SKILL_VERSION, scaffold: scaffoldVersion, intentSchema: INTENT_SCHEMA_VERSION, sdk: sdkVersion }
+}
+
+/**
+ * Compare a project's stamped scaffold version to the shipped one. Returns
+ * { from, to } when they differ (including a pre-versioning project with no
+ * versions block), or null when current. Forward-only — any mismatch means
+ * "a newer scaffold is available".
+ * @param {object} state - parsed .dashboard/state.json
+ * @param {string} scaffoldVersion - current shipped scaffold version (from the extracted kit)
+ */
+export function scaffoldDrift(state, scaffoldVersion) {
+  const stamped = state?.versions?.scaffold ?? null
+  return stamped === scaffoldVersion ? null : { from: stamped, to: scaffoldVersion }
+}
+
+/**
+ * Apply intent-schema migrations in sequence from intent.schemaVersion up to target.
+ * Registry: assets/scripts/migrations/intent-v<N>-to-v<N+1>.mjs (empty today — framework
+ * so a future schema bump is a drop-in file, not a refactor). Pure migrate(intent) functions.
+ * @param {object} intent
+ * @param {string} migrationsDir
+ * @param {number} [targetVersion=INTENT_SCHEMA_VERSION]
+ */
+export async function runIntentMigrations(intent, migrationsDir, targetVersion = INTENT_SCHEMA_VERSION) {
+  let v = intent.schemaVersion ?? 1
+  while (v < targetVersion) {
+    const file = join(migrationsDir, `intent-v${v}-to-v${v + 1}.mjs`)
+    if (!existsSync(file)) break
+    const { migrate } = await import(pathToFileURL(file).href)
+    intent = migrate(intent)
+    v++
+  }
+  intent.schemaVersion = Math.max(intent.schemaVersion ?? 1, v)
+  return intent
+}
+
+/**
+ * Check the installed @uipath/uipath-typescript version in a project.
+ * @param {string} projectPath
+ * @returns {{ ok: boolean, version: string|null }}
+ */
+export function checkSdkVersion(projectPath) {
+  const pkgPath = join(projectPath, 'node_modules', '@uipath', 'uipath-typescript', 'package.json')
+  if (!existsSync(pkgPath)) return { ok: false, version: null }
+  let version
+  try { version = JSON.parse(readFileSync(pkgPath, 'utf8')).version } catch { return { ok: false, version: null } }
+  const [maj = 0, min = 0, pat = 0] = String(version).split('.').map(Number)
+  const [rMaj, rMin, rPat] = MIN_SDK_VERSION.split('.').map(Number)
+  const ok = maj > rMaj || (maj === rMaj && (min > rMin || (min === rMin && pat >= rPat)))
+  return { ok, version }
+}
+
+/**
+ * Install dependencies in a project. Emits PREWARM_START/DONE/FAILED.
+ *
+ * Escalates on failure: `npm ci --prefer-offline` → `npm ci` → `npm install`.
+ * `npm ci` is fast + reproducible but STRICT — it aborts when package.json and
+ * package-lock.json are out of sync, which a lockfile generated by a different
+ * npm version can trigger ("Missing <pkg> from lock file" / "Invalid: lock file's
+ * <pkg> does not satisfy <pkg>"). The `npm install` fallback reconciles the lockfile
+ * and installs anyway, so a lockfile/npm-version drift can't block a build. For a
+ * local dev-preview build, resilience beats strict reproducibility.
+ * @param {string} projectPath - Absolute path to project directory
+ * @returns {Promise<void>}
+ */
+export async function runPrewarm(projectPath) {
+  emit('PREWARM_START')
+  const prewarmLock = join(projectPath, '.prewarm.lock')
+  writeAtomic(prewarmLock, String(Date.now()))
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+  const attempts = [`${npmCmd} ci --prefer-offline`, `${npmCmd} ci`, `${npmCmd} install`]
+
+  let lastErr = null
+  for (const cmd of attempts) {
+    try {
+      execSync(cmd, { cwd: projectPath, stdio: 'pipe' })
+      lastErr = null
+      break
+    } catch (e) {
+      lastErr = e
+      // After the last `npm ci` attempt fails, announce the `npm install` fallback.
+      if (cmd === `${npmCmd} ci`) {
+        log('⚠ npm ci rejected the lockfile (likely a lockfile/npm-version drift) — retrying with npm install…')
+      }
+    }
+  }
+  if (lastErr) {
+    const stderr = (lastErr.stderr?.toString() ?? String(lastErr)).slice(0, 500)
+    emit('PREWARM_FAILED', { exitCode: lastErr.status ?? 1, stderr })
+    try { unlinkSync(prewarmLock) } catch { /* ignore */ }
+    throw new Error(`dependency install failed: ${stderr}`)
+  }
+  try { unlinkSync(prewarmLock) } catch { /* ignore */ }
+  emit('PREWARM_DONE')
+}
+
+/**
+ * Block until node_modules/.package-lock.json appears (written by npm ci).
+ * Used when pre-warm was started in the background during plan review.
+ * Emits PREWARM_DONE or PREWARM_FAILED.
+ * @param {string} projectPath
+ * @param {number} [timeoutMs=300000]
+ */
+export function waitForPrewarm(projectPath, timeoutMs = 300_000) {
+  const signal = join(projectPath, 'node_modules', '.package-lock.json')
+  const deadline = Date.now() + timeoutMs
+  const startedAt = Date.now()
+  let lastLogAt = 0
+
+  while (!existsSync(signal)) {
+    const elapsed = Date.now() - startedAt
+
+    if (Date.now() > deadline) {
+      emit('PREWARM_FAILED', { exitCode: -1, stderr: `Timed out after ${Math.round(timeoutMs / 1000)}s` })
+      throw new Error(`Pre-warm timed out after ${Math.round(timeoutMs / 1000)}s`)
+    }
+
+    // Log progress every 20 seconds so the build output shows life
+    if (elapsed - lastLogAt >= 20_000) {
+      log(`⏳ Installing dependencies… (${Math.round(elapsed / 1000)}s)`)
+      lastLogAt = elapsed
+    }
+
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 500)
+  }
+
+  emit('PREWARM_DONE')
+}
+
+/**
+ * Kill a previously-started dev server using the PID stored in a file.
+ * Cross-platform: taskkill /T on Windows (kills process tree), SIGTERM on Unix.
+ * Waits up to 1500ms for the port to become free after killing.
+ * @param {string} pidFile - Absolute path to the .pid file
+ * @returns {Promise<void>}
+ */
+export async function killPreviousDevServer(pidFile) {
+  if (!existsSync(pidFile)) return
+
+  let pid
+  try {
+    pid = parseInt(readFileSync(pidFile, 'utf8').trim(), 10)
+  } catch { return }
+
+  if (!pid || isNaN(pid)) return
+
+  try {
+    if (process.platform === 'win32') {
+      // /T kills the entire process tree (npm → node → Vite); /F forces termination
+      execSync(`taskkill /PID ${pid} /T /F`, { stdio: 'pipe' })
+    } else {
+      process.kill(pid, 'SIGTERM')
+    }
+  } catch { /* process already dead — ignore */ }
+
+  // Wait for port to become free (up to 1500ms)
+  const deadline = Date.now() + 1500
+  while (Date.now() < deadline) {
+    const stillOpen = await new Promise(resolve => {
+      const socket = createConnection({ port: DASHBOARD_PORT, host: 'localhost' })
+      socket.once('connect', () => { socket.destroy(); resolve(true) })
+      socket.once('error', () => resolve(false))
+      socket.setTimeout(300, () => { socket.destroy(); resolve(false) })
+    })
+    if (!stillOpen) break
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 200)
+  }
+
+  try { unlinkSync(pidFile) } catch { /* ignore */ }
+}

package/skills/uipath-coded-apps/assets/scripts/dashboards/setup-admin-folder.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+/**
+ * setup-admin-folder.mjs — Idempotent AdminDashboards folder provisioning
+ *
+ * Creates the named folder and assigns Folder Administrator to the
+ * Administrators group. Skips steps already done.
+ *
+ * Usage:
+ *   node setup-admin-folder.mjs <FOLDER_NAME> [PROJECT_DIR]
+ *
+ * If PROJECT_DIR is provided, reads folderKey from .dashboard/state.json
+ * first and exits immediately if already provisioned.
+ */
+
+import { execFileSync }                         from 'child_process'
+import { existsSync, readFileSync, writeFileSync, renameSync } from 'fs'
+import { join, resolve }                        from 'path'
+
+const FOLDER_NAME = process.argv[2]
+const PROJECT_DIR = process.argv[3] ? resolve(process.argv[3]) : null
+
+if (!FOLDER_NAME) {
+  process.stderr.write('Usage: node setup-admin-folder.mjs <FOLDER_NAME> [PROJECT_DIR]\n')
+  process.exit(1)
+}
+
+// Pass argv as an array (NOT a shell string) so values like FOLDER_NAME can never
+// inject shell commands — execFileSync does not spawn a shell.
+function uip(args) {
+  return JSON.parse(execFileSync('uip', [...args, '--output', 'json'], { encoding: 'utf8' }))
+}
+
+function log(msg) { process.stdout.write(msg + '\n') }
+function fail(msg) { process.stderr.write(`ERROR: ${msg}\n`); process.exit(1) }
+
+function updateState(projectDir, folderKey, folderName) {
+  const fp    = join(projectDir, '.dashboard', 'state.json')
+  if (!existsSync(fp)) return
+  const state = JSON.parse(readFileSync(fp, 'utf8'))
+  state.deployment       = state.deployment ?? {}
+  state.deployment.folderKey  = folderKey
+  state.deployment.folderName = folderName
+  const tmp = fp + '.tmp'
+  writeFileSync(tmp, JSON.stringify(state, null, 2))
+  renameSync(tmp, fp)
+}
+
+async function main() {
+  // Fast-path: already provisioned
+  if (PROJECT_DIR) {
+    const statePath = join(PROJECT_DIR, '.dashboard', 'state.json')
+    if (existsSync(statePath)) {
+      const state = JSON.parse(readFileSync(statePath, 'utf8'))
+      if (state.deployment?.folderKey) {
+        log(`✓ Already provisioned (folderKey: ${state.deployment.folderKey})`)
+        process.exit(0)
+      }
+    }
+  }
+
+  log(`\n[Phase 1] Looking up role, group, and folder in parallel…`)
+
+  const [rolesResult, usersResult, foldersResult] = await Promise.all([
+    Promise.resolve(uip(['or','roles','list','--sort-by','Id asc','--limit','500'])),
+    Promise.resolve(uip(['or','users','list','--username','Administrators'])),
+    Promise.resolve(uip(['or','folders','list','--all','--name',FOLDER_NAME])),
+  ]).catch(e => fail(e.message))
+
+  // Extract Folder Administrator role key
+  const adminRole = rolesResult.Data?.find(r => r.Name === 'Folder Administrator')
+  if (!adminRole) fail('"Folder Administrator" role not found. Check: uip or roles list --output json')
+  const roleKey = adminRole.Key
+  log(`  ✓ Folder Administrator role: ${roleKey}`)
+
+  // Extract Administrators group key (case-insensitive)
+  const group = usersResult.Data?.find(u => {
+    const name = (u.UserName ?? u.Name ?? '').toLowerCase()
+    const type = (u.Type ?? u.type ?? '').toLowerCase()
+    return name === 'administrators' && (type.includes('group') || type === '')
+  })
+  if (!group) {
+    const available = (usersResult.Data ?? [])
+      .filter(u => (u.Type ?? '').toLowerCase().includes('group'))
+      .map(u => u.UserName ?? u.Name).join(', ')
+    fail(`"Administrators" group not found. Available groups: ${available || '(none)'}`)
+  }
+  const groupKey = group.Key
+  log(`  ✓ Administrators group: ${groupKey}`)
+
+  // Create folder if missing
+  let folderKey = foldersResult.Data?.find(f => f.Name === FOLDER_NAME)?.Key
+  let folderJustCreated = false
+
+  if (folderKey) {
+    log(`  ✓ Folder "${FOLDER_NAME}" already exists: ${folderKey}`)
+  } else {
+    log(`\n[Phase 2] Creating folder "${FOLDER_NAME}"…`)
+    const created = uip(['or','folders','create',FOLDER_NAME])
+    folderKey = created.Data?.Key ?? created.Key
+    if (!folderKey) fail('Could not extract folder key from create response')
+    folderJustCreated = true
+    log(`  ✓ Folder created: ${folderKey}`)
+  }
+
+  // Check if role already assigned (skip if folder was just created)
+  if (!folderJustCreated) {
+    log(`\n[Phase 3] Checking existing role assignment…`)
+    const userRoles = uip(['or','roles','user-roles','list','Administrators','--type','Group'])
+    const alreadyAssigned = userRoles.Data?.some(
+      r => (r.FolderPath ?? '').toLowerCase() === FOLDER_NAME.toLowerCase()
+        && (r.Role ?? '').toLowerCase() === 'folder administrator'
+    )
+    if (alreadyAssigned) {
+      log(`  ✓ Folder Administrator already assigned — nothing to do.`)
+      if (PROJECT_DIR) updateState(PROJECT_DIR, folderKey, FOLDER_NAME)
+      log(`\n✓ ${FOLDER_NAME} ready (key: ${folderKey})`)
+      return
+    }
+    log(`  Role not yet assigned — proceeding.`)
+  }
+
+  // Assign role — read existing roles first to avoid replacing them
+  log(`\n[Phase 4] Assigning Folder Administrator to Administrators…`)
+  log(`  ⚠ roles assign replaces existing roles. Reading current assignments first.`)
+
+  let existingRoleKeys = []
+  try {
+    const existingAssignments = uip(['or','roles','user-roles','list','Administrators','--type','Group'])
+    const folderRoles = existingAssignments.Data?.filter(
+      r => (r.FolderPath ?? '').toLowerCase() === FOLDER_NAME.toLowerCase()
+    )
+    existingRoleKeys = folderRoles?.map(r => r.RoleId ?? r.roleId).filter(Boolean) ?? []
+  } catch { /* ignore — folder is new or no existing assignments */ }
+
+  // Include new role key in the union
+  const allRoleKeys = [...new Set([...existingRoleKeys, roleKey])].join(',')
+  uip(['or','roles','assign','--user-key',groupKey,'--role-keys',allRoleKeys,'--folder-key',folderKey])
+  log(`  ✓ Role assigned.`)
+
+  if (PROJECT_DIR) updateState(PROJECT_DIR, folderKey, FOLDER_NAME)
+
+  log(`\n✓ ${FOLDER_NAME} is ready (key: ${folderKey})`)
+  log(`  Administrators group has Folder Administrator access.`)
+}
+
+main().catch(e => { process.stderr.write(`ERROR: ${e.message}\n`); process.exit(1) })

package/skills/uipath-coded-apps/assets/scripts/dashboards/tests/regime-eject.test.mjs

@@ -0,0 +1,124 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtempSync, writeFileSync, mkdirSync, existsSync, readFileSync } from 'node:fs'
+import { resolve, dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { tmpdir } from 'node:os'
+import { execFileSync } from 'node:child_process'
+import { packTemplate, VALID_EDIT_OPS, classifyEditIntent, parseEvent } from '../build-dashboard.mjs'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const SCRIPT = resolve(__dirname, '../build-dashboard.mjs')
+
+function tmp(prefix) {
+  return mkdtempSync(join(tmpdir(), prefix))
+}
+
+// ── EJECT is a recognized edit op ───────────────────────────────────────────────
+test('VALID_EDIT_OPS includes EJECT', () => {
+  assert.ok(VALID_EDIT_OPS.includes('EJECT'))
+})
+
+test('classifyEditIntent accepts a lone EJECT op', () => {
+  const r = classifyEditIntent({ projectDir: '/x', op: 'EJECT' })
+  assert.equal(r.ops.length, 1)
+  assert.equal(r.ops[0].op, 'EJECT')
+})
+
+// ── new lifecycle events are registered (parseEvent recognizes them) ────────────
+test('parseEvent recognizes the regime/template events', () => {
+  for (const ev of ['TEMPLATE_BUILD', 'EJECTED', 'EJECTED_PROJECT', 'TEMPLATE_PACKED']) {
+    const r = parseEvent(`${ev}:{"projectDir":"/x"}`)
+    assert.ok(r && r.type === ev, `${ev} should parse`)
+  }
+})
+
+// ── packTemplate stages a tenant-neutral modify-face + manifest ─────────────────
+test('packTemplate stages source + template.json, strips tenant identity', () => {
+  const P = tmp('packtmpl-')
+  mkdirSync(join(P, '.dashboard'), { recursive: true })
+  mkdirSync(join(P, 'src', 'metrics'), { recursive: true })
+  mkdirSync(join(P, 'dist'), { recursive: true })
+  mkdirSync(join(P, 'node_modules'), { recursive: true })
+  writeFileSync(join(P, '.dashboard', 'state.json'), JSON.stringify({
+    schemaVersion: 2, regime: 'ejected',
+    app: { name: 'Sales Template', routingName: 'sales-template-a1b2', semver: '2.1.0' },
+  }))
+  writeFileSync(join(P, 'intent.json'), '{ "schemaVersion": 2, "metrics": [] }')
+  writeFileSync(join(P, 'package.json'), '{ "name": "x" }')
+  writeFileSync(join(P, 'uipath.json'), JSON.stringify({
+    name: 'x',
+    scope: 'OR.Folders Insights',
+    clientId: 'SECRET-CLIENT-ID',
+    orgName: 'acme-org',
+    tenantName: 'acme-tenant',
+    baseUrl: 'https://acme.api.uipath.com',
+    redirectUri: 'http://localhost:25173',
+  }))
+  writeFileSync(join(P, 'src', 'metrics', 'm.ts'), 'export const fetchData = async () => []')
+  writeFileSync(join(P, 'dist', 'index.html'), '<html></html>')
+  writeFileSync(join(P, 'node_modules', 'junk.js'), 'junk')
+
+  packTemplate(P)
+
+  const S = join(P, 'dist', '_source')
+  // staged modify-face
+  assert.ok(existsSync(join(S, 'intent.json')), 'intent.json staged')
+  assert.ok(existsSync(join(S, 'src', 'metrics', 'm.ts')), 'src/ staged recursively')
+  assert.ok(existsSync(join(S, 'package.json')), 'package.json staged')
+  // uipath.json staged tenant-neutral: all tenant identity blanked, scope retained
+  const stagedCfg = JSON.parse(readFileSync(join(S, 'uipath.json'), 'utf8'))
+  assert.equal(stagedCfg.clientId, '', 'clientId blanked')
+  assert.equal(stagedCfg.orgName, '', 'orgName blanked')
+  assert.equal(stagedCfg.tenantName, '', 'tenantName blanked')
+  assert.equal(stagedCfg.baseUrl, '', 'baseUrl blanked')
+  assert.equal(stagedCfg.scope, 'OR.Folders Insights', 'scope retained')
+  assert.ok(!existsSync(join(S, 'node_modules')), 'node_modules excluded')
+  // manifest
+  const manifest = JSON.parse(readFileSync(join(S, 'template.json'), 'utf8'))
+  assert.equal(manifest.ejected, true)
+  assert.equal(manifest.regime, 'ejected')
+  assert.equal(manifest.routingName, 'sales-template-a1b2')
+  assert.equal(manifest.dashboardName, 'Sales Template')
+  assert.ok(manifest.sdkFloor && manifest.requiredScopes.includes('Insights'))
+})
+
+// ── EJECT flips regime; the edit-script then refuses ────────────────────────────
+test('EJECT op flips regime to ejected, then structured edits are refused', () => {
+  const P = tmp('eject-')
+  mkdirSync(join(P, '.dashboard'), { recursive: true })
+  writeFileSync(join(P, '.dashboard', 'state.json'), JSON.stringify({
+    schemaVersion: 2, regime: 'compiler-managed',
+    app: { name: 'X', routingName: 'x-1', semver: '1.0.0' }, widgets: {}, timeRange: '30d',
+  }))
+  const ejectIntent = join(P, 'eject-intent.json')
+  writeFileSync(ejectIntent, JSON.stringify({ op: 'EJECT', projectDir: P }))
+
+  const out = execFileSync('node', [SCRIPT, ejectIntent], { encoding: 'utf8' })
+  assert.match(out, /EJECTED:/)
+  const state = JSON.parse(readFileSync(join(P, '.dashboard', 'state.json'), 'utf8'))
+  assert.equal(state.regime, 'ejected')
+
+  // A structured edit on the now-ejected project must be refused (non-zero exit).
+  const rmIntent = join(P, 'rm-intent.json')
+  writeFileSync(rmIntent, JSON.stringify({ op: 'REMOVE', target: 'Foo', projectDir: P }))
+  let threw = false
+  try {
+    execFileSync('node', [SCRIPT, rmIntent], { encoding: 'utf8', stdio: 'pipe' })
+  } catch (e) {
+    threw = true
+    const combined = `${e.stdout ?? ''}${e.stderr ?? ''}`
+    assert.match(combined, /ejected|EJECTED_PROJECT/i)
+  }
+  assert.ok(threw, 'edit-script should exit non-zero on an ejected project')
+})
+
+// ── A template build records the ejected regime in state.json ──────────────────
+// (Build-side flag; the full build is exercised by the e2e task. Here we assert
+//  the regime computation only, via the documented default semantics.)
+test('absent regime is treated as compiler-managed (legacy state)', () => {
+  // classifyEditIntent + the runtime gate key off state.regime; legacy state with
+  // no regime must NOT be treated as ejected (would wrongly disable editing).
+  const legacy = { schemaVersion: 2, app: { name: 'L', routingName: 'l-1' } }
+  assert.notEqual(legacy.regime, 'ejected')
+})