Skip to content

feature: CI fat-script build pipeline + new OEM pattern docs#75

Closed
Gumbees wants to merge 2 commits into
developmentfrom
feature/oem-redo-foundation
Closed

feature: CI fat-script build pipeline + new OEM pattern docs#75
Gumbees wants to merge 2 commits into
developmentfrom
feature/oem-redo-foundation

Conversation

@Gumbees

@Gumbees Gumbees commented May 11, 2026

Copy link
Copy Markdown
Contributor

Summary

Foundation PR for the OEM redo design captured at #74. Lands the CI fat-script build pipeline and the doc updates that describe the new pattern. No OEM scripts move in this PR ... the Dell prototype follows in a separate PR branched off this one.

This is the load-bearing infra change that the rest of the OEM work sits on. It replaces the runtime lib-bootstrap approach (closed in #68) with CI-built self-contained scripts.

What lands

CI fat-script build pipeline

  • .github/workflows/build-fat-scripts.yml ... runs on push to development and main. Walks src/ for .ps1 files, processes # %INCLUDE <path-relative-to-repo-root> markers, writes fat scripts to the matching relative path on a separate published branch.
  • .github/scripts/build-fat-scripts.ps1 ... the include processor itself. ~80 lines, deliberately simple. Recursive includes are not supported in V1 (lib files cannot themselves contain # %INCLUDE markers) and the build fails loudly if it sees one.
  • Workflow tag handling ... push to main moves the release tag on published; push to development moves the dev tag. Commit message on published names the source short SHA and subject: build: from <source-sha-short> "<source commit subject>".
  • No-op safety ... if src/ is empty or missing, the workflow logs and skips cleanly (so this PR merging won't try to push an empty published branch ... the first real fat script lands when the Dell prototype merges).
  • Idempotent publish ... working tree is wiped (preserving .git) before each build so removed source files don't linger on published.

src/ directory stub

  • src/README.md explains the modular-source convention, the # %INCLUDE marker syntax, and how the build generates fat scripts in published. Nothing else under src/ yet ... the Dell prototype PR seeds it.

Documentation

  • CLAUDE.md gains a "Source vs Published" section (build pipeline, marker syntax, URL convention) and a new "OEM Vendor Scripts" section that captures:
    • Internet check at the install step only (with example function)
    • configure not baseline naming convention (with old→new rename table)
    • Canonical BIOS-settings translation pattern ($env:BIOS_* env vars, shared map per OEM)
    • Standard OEM script layout under src/
  • README.md gains a "Script Delivery" section that summarizes the source→published flow and pins the canonical jsDelivr URL convention.
  • script-template-powershell.ps1 ... no lib-bootstrap block (was never on development, only ever in the closed PR improvement(docs): lib-bootstrap pattern + development branch model + jsDelivr URLs #68). Added a commented-out # %INCLUDE example block at the top and a commented-out internet-check stub before the script-logic section with a note explaining when to uncomment.

Canonical script URL

https://cdn.jsdelivr.net/gh/dtc-inc/msp-script-library@release/<path>
  • @release ... production-pinned tag on published, moved on each push to main.
  • @dev ... staging tag on published, moved on each push to development.
  • @<commit-sha> ... immutable per-build pin for customer-facing presets where you want to lock the exact build.

Variance from the design issue

None substantive. Two implementation choices worth noting:

  • # %INCLUDE path is relative to the repo root, not relative to src/. This matches the marker example in the design (# %INCLUDE oem-shared/lib/...) and makes the path stable whether the build moves where source lives. In-source includes will end up looking like # %INCLUDE src/oem-shared/lib/... ... explicit, no magic resolver.
  • Empty-src no-op gate. The workflow checks for src/ and at least one .ps1 before doing anything. Lets this PR land cleanly before the Dell prototype seeds src/.

Test plan

  • CI: workflow parses cleanly on push to the PR branch (the if: gate on has_src=false should make this PR's own merge to development produce a clean "nothing to build" run, since src/ only contains the README).
  • CI: after the Dell prototype lands and seeds src/, the workflow produces a published branch with fat output and a moved dev tag.
  • Local: run .github/scripts/build-fat-scripts.ps1 against a stub src/ with a leaf that includes a lib; verify the inlined output has the framing comments and the lib content in place of the marker.
  • Local: verify the build script fails loudly when a lib contains a # %INCLUDE marker (recursive include guard).
  • Doc render: confirm CLAUDE.md and README.md render correctly on GitHub web view.

Follow-ups

Lands the foundation for the OEM redo design (#74):

- GHA workflow + build script that walks src/ for .ps1 files, processes
  `# %INCLUDE <path>` markers, writes fat self-contained scripts to a
  separate `published` branch. Push to main moves @Release tag; push to
  development moves @dev tag. Recursive includes rejected loudly.
- src/ stub with README explaining the modular-source convention and
  marker syntax.
- CLAUDE.md: new "Source vs Published" section (build pipeline + URL
  convention) and "OEM Vendor Scripts" section (internet-check at
  install step only, `configure` not `baseline` naming, canonical
  $env:BIOS_* translation pattern, standard OEM layout).
- README.md: "Script Delivery" section with the canonical jsDelivr URL.
- script-template-powershell.ps1: commented-out `# %INCLUDE` example
  block + commented-out internet-check stub.

No OEM scripts move in this PR ... Dell prototype is a follow-up
branched from this PR.
@Gumbees Gumbees added type:enhancement New work that adds or improves capability (Halo: Enhancement) category:feature Net-new capability the customer/operator didn't have labels May 11, 2026

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Code review skipped — your organization's overage spend limit has been reached.

Code review is billed via overage credits. To resume reviews, an organization admin can raise the monthly limit at claude.ai/admin-settings/claude-code.

Once credits are available, push a new commit or reopen this pull request to trigger a review.

@Gumbees

Gumbees commented May 11, 2026

Copy link
Copy Markdown
Contributor Author

Closing in favor of a design refinement on #74. After review, the CI fat-script build pipeline (src/ + published/ branch + # %INCLUDE markers + GHA assembly) is overengineered for this repo's scale (~12 scripts that'd benefit from shared helpers, 5 contributors). The build-system costs (custom marker syntax, branch choreography, two trees to grep when debugging, GHA as a critical path) outweigh the DRY-at-source benefit at current size.

Replacing with self-contained scripts: each OEM script inlines its own OEM detection + BIOS translation table + any other helpers it needs. ~30-50 lines duplicated across Dell + HP + Lenovo. Acceptable, easy to grep, no build system to operate.

The genuinely-good pieces of the prior design are being preserved in the new shape:

  • configure naming (not baseline)
  • $env:BIOS_* canonical settings with per-OEM translation tables
  • Internet check at install step only
  • Per-OEM script shape: *-configure.ps1 / *-command-update-install.ps1 / *-command-update-run.ps1 / *-debloat.ps1

Branch retained for cherry-pick reference. New Dell PR coming as a fresh PR targeting development.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

category:feature Net-new capability the customer/operator didn't have type:enhancement New work that adds or improves capability (Halo: Enhancement)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant