Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 105 additions & 0 deletions .github/workflows/kit-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,9 @@ jobs:
for f in bin/workshop-kit.mjs src/index.mjs src/config/*.mjs src/commands/*.mjs tools/tenant-pulse-dashboard/server.mjs; do
node --check "$f"
done
# Shared Python that no build step exercises, so nothing else would
# catch a syntax error in it before an author ran it against a deck.
python3 -c "import ast,sys; ast.parse(open(sys.argv[1]).read(), sys.argv[1])" tools/extract-pptx-assets.py

- name: CLI responds
run: |
Expand Down Expand Up @@ -124,3 +127,105 @@ jobs:
grep -q 'keep={{WORKSHOP_UNDECLARED}}' "$work/got.txt" || { echo 'FAIL: undeclared token should stay literal'; exit 1; }
grep -q '{{WORKSHOP_UIPATH_ORG_NAME}}' "$work/downloads/project/AGENTS.md" || { echo 'FAIL: source file was mutated'; exit 1; }
echo 'zip pipeline OK'

# This prune DELETES files from static/downloads/, so it is covered the same
# way. The regression it guards: static/downloads/ is gitignored, so a stale
# ZIP is invisible to CI and code review, yet `codedapp pack` packs the local
# build/ dir that Docusaurus fills from static/ -- so it still reaches the
# deployed site.
- name: ZIP prune removes orphans, spares current zips and non-zips
run: |
set -e
work="$(mktemp -d)"
mkdir -p "$work/config" "$work/downloads/keep-me" "$work/static/downloads"
cat > "$work/config/workshop-targets.json" <<'JSON'
{
"title": "Fixture", "tagline": "t", "repo": "org/repo",
"defaultTarget": "local",
"targets": {"local": {
"siteUrl": "http://localhost:3000", "baseUrl": "/",
"workshop": {"uipathOrgName": "org", "uipathTenantName": "tenant",
"uipathTenantUrl": "https://example.invalid/org/tenant",
"orchestratorParentFolder": "Shared"},
"codedApp": {"name": "fixture"}
}}
}
JSON
printf 'content\n' > "$work/downloads/keep-me/file.txt"
: > "$work/static/downloads/orphan.zip"
: > "$work/static/downloads/notes.txt"
# Seed the CURRENT zip too. This models a rebuild, which is the only
# state in which a prune that ignores its keep-set is observable: on a
# fresh tree there is no current zip present for it to wrongly delete.
: > "$work/static/downloads/keep-me.zip"

out="$( cd "$work" && node "$GITHUB_WORKSPACE/bin/workshop-kit.mjs" zip-downloads 2>&1 )"
echo "$out"
echo "$out" | grep -q 'Removed orphaned static/downloads/orphan.zip' || { echo 'FAIL: orphan not reported'; exit 1; }
[ -e "$work/static/downloads/orphan.zip" ] && { echo 'FAIL: orphan zip survived'; exit 1; }
[ -e "$work/static/downloads/keep-me.zip" ] || { echo 'FAIL: current zip missing'; exit 1; }
[ -e "$work/static/downloads/notes.txt" ] || { echo 'FAIL: non-zip file was deleted'; exit 1; }
# The prune runs BEFORE generation, so deleting a current zip is invisible
# by file existence alone -- it is immediately recreated. Assert on the log
# instead, or a prune that ignores its keep-set passes unnoticed.
echo "$out" | grep -q 'Removed orphaned static/downloads/keep-me.zip' && { echo 'FAIL: current zip reported as orphaned'; exit 1; }

# Emptying downloads/ makes every remaining zip an orphan. This is the
# exact shape of the CA bug: the folder was deleted, the zip was not.
rm -rf "$work/downloads/keep-me"
out2="$( cd "$work" && node "$GITHUB_WORKSPACE/bin/workshop-kit.mjs" zip-downloads 2>&1 )"
echo "$out2"
[ -e "$work/static/downloads/keep-me.zip" ] && { echo 'FAIL: zip survived deletion of its source folder'; exit 1; }
[ -e "$work/static/downloads/notes.txt" ] || { echo 'FAIL: non-zip file was deleted'; exit 1; }

# No downloads/ at all means the kit is not managing that directory, so
# it must not delete anything there.
rm -rf "$work/downloads"
: > "$work/static/downloads/untouched.zip"
( cd "$work" && node "$GITHUB_WORKSPACE/bin/workshop-kit.mjs" zip-downloads >/dev/null 2>&1 )
[ -e "$work/static/downloads/untouched.zip" ] || { echo 'FAIL: pruned with no downloads/ dir'; exit 1; }
echo 'zip prune OK'

# The prune DELETES build artifacts, so it gets the same treatment as the
# ZIP pipeline. The case that matters is the second one: one repo packs a
# different app name per training target, and a global "keep the newest N"
# would destroy an older target's only package.
- name: Package prune keeps N per package name
run: |
set -e
work="$(mktemp -d)"
mkdir -p "$work/.uipath"
cd "$work/.uipath"
# older <- -> newer, within each name
for f in only-once.0.1.0-20260101000000 \
many.0.1.0-20260101000000 many.0.1.0-20260102000000 \
many.0.1.0-20260103000000 many.0.1.0-20260104000000; do
echo x > "$f.nupkg"
done
touch -t 202601010000 only-once.0.1.0-20260101000000.nupkg
touch -t 202601010000 many.0.1.0-20260101000000.nupkg
touch -t 202601020000 many.0.1.0-20260102000000.nupkg
touch -t 202601030000 many.0.1.0-20260103000000.nupkg
touch -t 202601040000 many.0.1.0-20260104000000.nupkg
echo '{}' > app.config.json
echo 'not-a-package' > loose.nupkg

cd "$work"
node --input-type=module -e "
const {prunePackages} = await import('file://$GITHUB_WORKSPACE/src/commands/codedapp-deploy.mjs');
prunePackages();
"

# The single old package of a name never packed again must survive,
# even though four newer files exist under a different name.
[ -f .uipath/only-once.0.1.0-20260101000000.nupkg ] \
|| { echo 'FAIL: pruned the only package of an untouched name'; exit 1; }
[ "$(ls .uipath/many.*.nupkg | wc -l)" -eq 3 ] \
|| { echo 'FAIL: expected 3 survivors for "many"'; exit 1; }
[ -f .uipath/many.0.1.0-20260101000000.nupkg ] \
&& { echo 'FAIL: oldest of the group survived'; exit 1; }
[ -f .uipath/many.0.1.0-20260104000000.nupkg ] \
|| { echo 'FAIL: newest of the group was deleted'; exit 1; }
[ -f .uipath/app.config.json ] || { echo 'FAIL: app.config.json removed'; exit 1; }
[ -f .uipath/loose.nupkg ] || { echo 'FAIL: unparseable filename removed'; exit 1; }
echo 'package prune OK'
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,7 @@ npm-debug.log*

# Build output
/dist

# Byte cache from the Python extractor
__pycache__/
*.pyc
119 changes: 113 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,8 @@ src/commands/ one module per CLI subcommand
src/components/ WorkshopEnv React components
src/css/ shared stylesheet
agents/base.md THE shared "General Workshop Instructions"
schemas/ JSON Schema for config/workshop-targets.json
tools/ tenant pulse dashboard
schemas/ JSON Schema for config/workshop-targets.json and the PPTX slide map
tools/ tenant pulse dashboard, PPTX asset extractor
template/ scaffold for `workshop-kit init` (a complete, building site)
```

Expand All @@ -35,9 +35,10 @@ workshop-kit agents build regenerate AGENTS.md from base + product
workshop-kit agents check fail if AGENTS.md is stale or hand-edited inside the fence
workshop-kit check:tenant-access advisory tenant permission report (never fails a build)
workshop-kit build --target <name>
workshop-kit codedapp <check|pack|publish|deploy|all>
workshop-kit codedapp <check|pack|publish|deploy|all> pack prunes old nupkgs
workshop-kit preview --target <name>
workshop-kit pulse
workshop-kit extract-pptx --pptx <f> --output-root <d> --manifest <f>
workshop-kit validate-config check every target in config/workshop-targets.json
workshop-kit doctor [target]
workshop-kit repin <tag> move a content repo onto a released kit tag
Expand Down Expand Up @@ -119,6 +120,83 @@ Everything else is content.
Replace the `REPLACE_ME` tenant values before delivering; `validate-config`
deliberately passes with them in place, since it cannot know what is real.

## Packing and deploying the Coded App

`workshop-kit codedapp <check|pack|publish|deploy|all>` builds the site for a
target and ships it as a UiPath Coded Web App. `check` prints the resolved
target, app name and whether the deploy env is present, and touches nothing.

Every `pack` writes a fresh timestamped `.uipath/<name>.<version>.nupkg`, and
`uip` never removes one. Left alone that grows without bound — one repo reached
147 MB across 21 files in two months. After a successful pack the kit keeps the
newest **3 packages per package name** and deletes the rest, reporting what it
removed. Override with `UIPATH_CODEDAPP_KEEP`; a value below 1 or non-numeric
falls back to 3 with a warning.

Per *name*, not per directory, because a repo packs a different app name per
training target — `tc20260721-ca-workshop`, `ifca20260722-ca-workshop`, and so
on. A global "keep the newest 3" would delete an older target's only package the
moment you pack a different one, and `publish` is a separate command that runs
against the local file, so that would break pack-now-publish-later. Grouping by
name also guarantees the file the current run just produced survives.

Local packages are build artifacts, not the deliverable: `publish` uploads to
Orchestrator. `.uipath/` and `uipath.json` are gitignored in every content repo
and must never be committed. Files in `.uipath/` that are not named
`<name>.<semver>.nupkg` — including `app.config.json` and `metadata.json` — are
left alone.

## Extracting a workshop from a facilitator deck

`workshop-kit extract-pptx` pulls screenshots, ordered text blocks and callout
geometry out of a `.pptx` and writes a manifest beside them. Two workshops were
built this way from a lab-guide deck.

```bash
npx workshop-kit extract-pptx \
--pptx ~/decks/5_\ CM\ Lab\ Guide.pptx \
--output-root static/img \
--manifest extraction/manifest.json \
--slide-map extraction/slide-map.json
```

Run it once without `--slide-map` first. Everything lands in
`static/img/unassigned/`, which is what you want before you know where the
exercise boundaries are. Then write the map and run it again:

```json
{
"deck": "5_ CM Lab Guide.pptx",
"pages": [
{"page": "pre-reqs", "slides": [2]},
{"page": "exercise-1", "slides": ["3-18"]},
{"page": "exercise-2", "slides": ["20-24"]}
],
"roles": [
{"role": "answer-reveal", "match": ["answers"]},
{"role": "sign-in", "slides": [2]}
]
}
```

`schemas/pptx-slide-map.schema.json` has the full shape. The map is the *only*
deck-specific input; it lives in the content repo, or nowhere at all once the
docs are the source of truth, and the deck itself is never committed.

Two things this tool exists to get right, both learned the hard way:

- **Placeholder pictures count.** An image dropped into a PowerPoint content
placeholder is a `PlaceholderPicture` with `shape_type == PLACEHOLDER`, not
`PICTURE`. An earlier per-repo copy filtered on `shape_type` alone and silently
dropped 18 of 33 screenshots from one deck, with no error and no non-zero exit.
- **Numbered callout ovals are separate shapes.** They vanish the moment a
screenshot is extracted on its own, so each is recorded as a percentage offset
inside the picture it overlaps, ready for `.workshop-click-marker` in MDX.

`python-pptx` and `Pillow` are required, and are deliberately not project
dependencies — this is a one-off authoring step, not part of any build. The
command checks for them and prints the `pip install` line if they are absent.

## Why the components are compiled

`npm run build` emits `src/components/*.tsx` to `dist/` as plain JS plus
Expand All @@ -134,9 +212,38 @@ against a `file:` link.

## Versioning

- `agents/base.md` wording, or a new optional config field → **minor**
- new CLI command, `agents/base.md` wording, or a new optional config field → **minor**
- check or pipeline bug fix → **patch**
- renamed component, removed config field, changed CLI flag → **major**

Content repos pin a caret range and rely on Dependabot to surface kit releases,
so a shared change is immediately CI-tested against every workshop.
**The version number is a signal, not a trigger. Nothing updates on its own.**

A content repo pins one exact tag:

```json
"@uipath-lab-tec/workshop-kit": "github:UiPath-LAB-TEC/workshop-kit#v1.3.0"
```

That is a tag, not a caret range, and it resolves through `package-lock.json` to
a specific commit. Three consequences follow, and all three are deliberate:

1. **Dependabot cannot bump it.** There is no registry to poll and no semver
range to compare for a `github:` tag dependency. The `dependabot.yml` in each
content repo covers `@docusaurus/*` and GitHub Actions only — a kit group
used to sit there doing nothing, which read as if the bumps were automatic.
2. **`npm install` cannot bump it either.** The lockfile records the resolved
commit of the *previous* tag, so npm honours the lock, prints "changed 1
package", and keeps the old kit even after you edit `package.json`. See
"Releasing, and repinning consumers" above.
3. **Only `workshop-kit repin <tag>` moves a repo**, and someone has to run it,
per repo, on purpose.

So a **major** does not break every workshop the day it is tagged. It breaks the
next repo that repins, whenever that is. A workshop already delivered can sit on
an old tag indefinitely and keep building — which is the point, because a repo
is often frozen mid-delivery while the kit moves on.

The cost of that safety is that a shared fix is *not* live everywhere until you
repin each repo. Cross-repo CI proves a change is safe; it does not deliver it.
Treat "tag the kit" and "repin the consumers" as two separate jobs, and expect
repos to sit on different tags in between.
Loading
Loading