verify-new-sample-pr

name	verify-new-sample-pr
description	Verify a "new sample" PR in pnp/sp-dev-fx-aces builds successfully, then produce a deployment + testing checklist from the sample README so it can be manually deployed and tested before merging. Use when: reviewing a PR that adds a brand-new ACE sample, "verify new sample PR", "test new sample before merging", checking a first-time contributor submission. Detects PR type from the PR template Q&A table, builds the sample, locates the generated .sppkg, extracts/summarizes deployment and testing steps (and required API permission approvals) from the README, flags missing README guidance, and defers cleanup until the user confirms manual testing passed.
argument-hint	<PR number or URL>

Verify New Sample PR

Companion to the verify-sample-pr-build skill (use that one for upgrade/fix PRs — a straight compile/build check is enough there). This skill is for PRs that introduce a brand-new sample into samples/<SampleName>/, where a human needs to manually deploy the generated .sppkg and validate it actually works before merging.

When to Use

• PR template body has New sample? | yes
• First-time contributor submitting an entirely new ACE sample
• You need a deployment + testing checklist, not just a compile check

Known Tool Quirk: Verify Your Working Directory

The terminal tool can silently "simplify" a chained cd <path> && <command> and drop the cd, leaving a stale cwd from a previous task/session in place. This has caused commands to silently run against the wrong sample folder.

Mitigation — apply both:

1. Prefer absolute paths over cd. Use npm --prefix /abs/path/to/samples/<Name> install and npm --prefix /abs/path/to/samples/<Name> run build instead of cd ... && npm .... This works regardless of the shell's persisted cwd.
2. If you must cd, issue it as its own standalone command, then immediately run pwd as a separate call and confirm it matches the expected sample path before running anything else. Never assume a chained cd took effect.

Procedure

1. Confirm this is a "new sample" PR

Detect from the PR body's Q&A table (this repo's PR template has rows like Bug fix? / New feature? / New sample?):

gh pr view <PR_NUMBER> --repo pnp/sp-dev-fx-aces --json body --jq '.body'

Or use get-pr-type.sh, which prints new-sample, upgrade-or-fix, or ambiguous.

If ambiguous (leftover placeholder text, multiple rows marked yes, or no clear answer) — ask the user to confirm before proceeding. If it turns out to be an upgrade/fix PR, use the verify-sample-pr-build skill instead.

2. Identify the affected sample folder(s)

gh pr view <PR_NUMBER> --repo pnp/sp-dev-fx-aces --json files --jq '.files[].path' \
  | grep -oE '^samples/[^/]+' | sort -u

Or get-changed-samples.sh. A new-sample PR should touch exactly one new samples/<Name>/ folder — if it touches more than one, or modifies existing unrelated samples, flag that to the user.

3. Check out the PR branch locally

gh pr checkout <PR_NUMBER> --repo pnp/sp-dev-fx-aces

Local-only and fully reversible — does not touch remote/origin.

4. Determine Node.js version & toolchain, then build

Same detection logic as verify-sample-pr-build. Use the sample's absolute path throughout (see cwd-safety note above) — do not rely on a prior cd:

1. Check package.json → engines.node, or .yo-rc.json → nodeVersion
2. nvm install <version> && nvm use <version>
3. npm --prefix <abs-path>/samples/<SampleName> install
4. Build:
   • Heft toolchain (SPFx 1.21+, no gulpfile.js): npm --prefix <abs-path>/samples/<SampleName> run build
   • Gulp toolchain (older samples, has gulpfile.js): (cd <abs-path>/samples/<SampleName> && npx gulp bundle --ship && npx gulp package-solution --ship) — run as a single subshell command so the cd can't be dropped or leak into later commands.

After each step, sanity-check output paths/errors reference the expected sample folder name — if they reference a different sample, stop and re-verify cwd.

If the build fails: stop here, report the errors, clean up (step 9), and do not proceed to README/deployment analysis for a broken build.

5. Locate and report the .sppkg

find samples/<SampleName>/sharepoint/solution -name '*.sppkg'

Report the full absolute path so the user can copy/download it for manual deployment to a SharePoint app catalog.

6. Check for required API permission approvals

New samples that call Microsoft Graph or other APIs often declare webApiPermissionRequests in config/package-solution.json. These must be approved in the SharePoint Admin Center → API access page after the package is deployed, or the ACE will fail at runtime — this is easy for a README to omit.

./scripts/get-api-permissions.sh samples/<SampleName>

Always surface these explicitly in the checklist, regardless of whether the README mentions them.

7. Extract a deployment + testing checklist from the README

Read samples/<SampleName>/README.md and produce a summarized, actionable checklist (not a verbatim quote) covering:

• Prerequisites: tenant settings, site/list provisioning, sample data, feature flags
• Deployment steps: upload to app catalog, trust/deploy, approve the API permissions found in step 6, any ACE property-pane config needed
• How to add the ACE: Viva Connections dashboard / Teams / SharePoint page
• How to verify it works: expected behavior, what to click, what result to expect

Flag gaps explicitly. If the README is missing any of the above — e.g. no mention of the Graph permissions found in step 6, no clear "how to test" section, missing prerequisite setup (like a required SharePoint list schema or sample data) — call it out as "missing from README — consider asking the PR author to add this" so the user can request changes from the contributor before merging.

8. Present results and STOP — wait for manual confirmation

Report: build status, .sppkg absolute path, deployment checklist, testing checklist, and any README gaps found. Then pause and wait. Do not clean up yet — the user needs the checked-out branch/build artifacts while they manually download, deploy, and test the package.

9. Clean up only after explicit confirmation

Once the user confirms manual testing passed (e.g. "all ok"):

./scripts/cleanup-sample-build.sh <abs-path>/samples/<SampleName>

(uses absolute paths internally, no cd required)

Then return to the repo root and switch branches as standalone commands, verifying with pwd:

cd <abs-repo-root>
pwd   # confirm it printed the repo root before continuing
git checkout main
git branch -D <pr-branch-name>

Finally, verify with git status --short that the sample folder has no leftover untracked build artifacts (e.g. toolchain-specific output directories the cleanup script doesn't yet know about). If something remains, remove it manually and consider adding it to cleanup-sample-build.sh for next time.

If the user reports a problem instead, keep the branch and build artifacts in place so they can keep investigating — only clean up once they're done or ask to abandon it.

Notes

• Never push, comment on, or merge the PR yourself — only report findings and act on the user's explicit instructions.
• gh pr checkout and git branch -D only ever affect the local clone.
• npm install deprecation/audit warnings on older transitive deps are normal and not a build failure signal.
• Always double-check the working directory before running install/build/cleanup commands — see the cwd-safety note above. Prefer absolute paths and npm --prefix over relying on cd persisting across tool calls.