diff --git a/agents/base.md b/agents/base.md index 08fa6c4..1441ce1 100644 --- a/agents/base.md +++ b/agents/base.md @@ -38,8 +38,36 @@ This section is shared workshop guidance. Keep it exactly the same across worksh - Verify MDX changes with `npm run build` when practical; the repo scripts should run the docs preparation and checks automatically. Before deploying a target, run `npm run build:target -- `. ### Workshop Configuration Variables -- Session-specific workshop values must come from `.env` via `docusaurus.config.ts` `customFields.workshop`; do not hard-code them in docs. -- Required variables are `WORKSHOP_UIPATH_ORG_NAME`, `WORKSHOP_UIPATH_TENANT_NAME`, `WORKSHOP_UIPATH_TENANT_URL`, and `WORKSHOP_ORCHESTRATOR_PARENT_FOLDER`. + +There are three separate configuration surfaces. They are not interchangeable, +and each has exactly one owner. If you are unsure where a value belongs, ask +which of these three reads it. + +**1. `config/workshop-targets.json` — everything participants see. Committed.** +- The single source for org name, tenant name, tenant URL and parent folder. Per target, under `targets..workshop`. +- `createWorkshopConfig()` reads it at build time and publishes it as Docusaurus `customFields.workshop`; the `WorkshopEnv` components read it from there. Docs never see a file or an env var. +- Every `workshop-kit` command reads the same file, so the CLI and the rendered site can never disagree. +- Safe for participants to read. Never put a folder key, credential, token or any deployment-only value here. +- Base fields are `uipathOrgName`, `uipathTenantName`, `uipathTenantUrl`, `orchestratorParentFolder`, rendered by the tokens `WORKSHOP_UIPATH_ORG_NAME`, `WORKSHOP_UIPATH_TENANT_NAME`, `WORKSHOP_UIPATH_TENANT_URL`, `WORKSHOP_ORCHESTRATOR_PARENT_FOLDER`. Declare anything extra under `extraFields`, which derives the token, the type and the payload from one place. + +**2. `.env.deploy.` — deployment only. Git-ignored, never committed.** +- Read by the `codedapp` commands and nothing else. It has no effect on the built site. +- Supplies exactly three values: `UIPATH_FOLDER_KEY` (required to deploy), `UIPATH_CODEDAPP_VERSION` and `UIPATH_CODEDAPP_AUTHOR` (both optional). +- An already-set process env var wins over the file. +- Copy `.env.deploy.example` to `.env.deploy.` to create one. + +**3. `.env` and `.env.` — the tenant pulse dashboard only.** +- Read by `workshop-kit pulse` and nothing else. Not by the build, not by the docs, not by deployment. +- Supplies `WORKSHOP_TARGET`, `WORKSHOP_START`, `WORKSHOP_END`, `RE_CONTEXT`. +- A plain `.env` does **not** feed workshop values into the site. If you find `WORKSHOP_UIPATH_*` keys in a `.env`, they are dead leftovers from before the kit; the values in `config/workshop-targets.json` are what actually render. Do not add them, and do not trust them when they are there. + +**Choosing the target.** All three layers are keyed by target name. Precedence is +an explicit CLI argument (`workshop-kit build `), then the +`WORKSHOP_TARGET` env var, then `defaultTarget` in +`config/workshop-targets.json`. `build:target` and `start:target` set +`WORKSHOP_TARGET` for the Docusaurus process. + +Other rules for these values: - Use `WorkshopValue`, `WorkshopLink`, or `WorkshopCodeBlock` from `src/components/WorkshopEnv.tsx` when showing these values in MDX. - In copyable prompts, use `WorkshopCodeBlock` and tokens such as `{{WORKSHOP_UIPATH_ORG_NAME}}` so rendered prompts include the current session values. - Keep participant-specific names such as participant folder names and exercise bucket names as explicit placeholders unless a dedicated workshop variable exists for them. diff --git a/bin/workshop-kit.mjs b/bin/workshop-kit.mjs index 9c37cf3..e4af01e 100755 --- a/bin/workshop-kit.mjs +++ b/bin/workshop-kit.mjs @@ -25,7 +25,7 @@ const USAGE = `workshop-kit codedapp pulse tenant pulse dashboard validate-config check every target in config/workshop-targets.json - doctor report kit version, resolved target and drift + doctor [target] report kit version, resolved target and drift init --product [--title ] scaffold a new workshop repo --help, --version @@ -167,8 +167,12 @@ async function main() { } case 'doctor': { + // Accepts a target the same way build/start/preview do. Without this it + // silently reported the default target while the caller believed they + // were inspecting the one they named. + const target = takeTarget(argv); const {doctor} = await import(join(commandsDir, 'doctor.mjs')); - return doctor({}); + return doctor({target}); } case 'init': { diff --git a/package.json b/package.json index 4664fc9..1d53f1e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@uipath-lab-tec/workshop-kit", - "version": "1.1.0", + "version": "1.2.0", "description": "Shared Docusaurus infrastructure for UiPath LAB TEC workshop repos.", "license": "UNLICENSED", "type": "module", diff --git a/src/commands/doctor.mjs b/src/commands/doctor.mjs index cd19000..24cdcc9 100644 --- a/src/commands/doctor.mjs +++ b/src/commands/doctor.mjs @@ -14,7 +14,7 @@ import {agentsCheck} from './agents-build.mjs'; const kitRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..'); -export function doctor({root = process.cwd()} = {}) { +export function doctor({root = process.cwd(), target: explicitTarget} = {}) { const kit = JSON.parse(readFileSync(join(kitRoot, 'package.json'), 'utf8')); const notes = []; @@ -39,7 +39,7 @@ export function doctor({root = process.cwd()} = {}) { console.log(`default ${config.defaultTarget}`); try { - const {targetName, target} = getTarget(); + const {targetName, target} = getTarget(explicitTarget); console.log(`resolved ${targetName} -> ${target.siteUrl}${target.baseUrl}`); console.log(`tenant check ${target.requiresTenantAccess ? 'enabled' : 'disabled'} for this target`); } catch (error) { diff --git a/src/config/createWorkshopConfig.mjs b/src/config/createWorkshopConfig.mjs index 8391e49..008e741 100644 --- a/src/config/createWorkshopConfig.mjs +++ b/src/config/createWorkshopConfig.mjs @@ -1,7 +1,8 @@ /** * Docusaurus config factory. Owns everything the three workshop sites had * identical: the classic preset, themeConfig, navbar and footer shape, - * onBrokenLinks, i18n, future flags, and the customFields.workshop wiring. + * onBrokenLinks/onBrokenAnchors, i18n, future flags, and the customFields.workshop + * wiring. * * A content repo's docusaurus.config.ts becomes: * @@ -100,6 +101,12 @@ export function createWorkshopConfig(overrides = {}) { projectName, onBrokenLinks: 'throw', + // Set explicitly, though 'warn' is also the Docusaurus default: a renamed + // heading breaks every in-page link pointing at it, and a workshop + // accumulates that as exercises are reordered. Deliberately not 'throw' — + // a stale anchor is a content bug, not a reason to block a deploy the day + // of a workshop. Read the build output rather than trusting a green exit. + onBrokenAnchors: 'warn', i18n: { defaultLocale: 'en',