diff --git a/.prettierrc.json b/.github/linters/.prettierrc.json similarity index 100% rename from .prettierrc.json rename to .github/linters/.prettierrc.json diff --git a/AGENTS.md b/AGENTS.md index 505539b..233473b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,30 +1,29 @@ # Agents -This repository is the central documentation for the MSX ecosystem. Everything an agent needs to work here — and the roles agents play across the ecosystem — is documentation, read the same way a new teammate would. +## Main directive -## Start here +Everything is a work in progress and can be updated and improved. +If you find a problem, fix it if it's small; otherwise, register it as an issue in the respective repo. -1. Read this file, then the [README](README.md) for what this repository is and how it builds. -2. Read the [Ways of Working](https://msxorg.github.io/docs/Ways-of-Working/) — how work flows from idea to delivery. -3. Load the [Coding Standards](https://msxorg.github.io/docs/Coding-Standards/) relevant to the change. +## Install the ecosystem -## Roles +1. Create a folder in the home directory called `.msx`: +2. Clone the ecosystem locally: + 1. — requires PRs to be updated. + - Clone as bare and use worktrees. + - Create a worktree for all branches - worktree = name of the branch. + 2. — work directly towards main. + - Simple clone, only main. -Agent behaviour is authored once, as documentation, in the [Agents](https://msxorg.github.io/docs/Agents/) section. Use the role that fits the task: +To install: +- Clone the repos in the users home folder under a sub-folder named `.msx`. +- Set configs locally to each of these repos using the GitHub username and email. -- [Define](https://msxorg.github.io/docs/Agents/define/) — capture, refine, and plan a change into an issue. -- [Implement](https://msxorg.github.io/docs/Agents/implement/) — deliver a planned issue as a review-ready pull request. -- [Reviewer](https://msxorg.github.io/docs/Agents/reviewer/) — review a pull request for delivery, taste, and security. -- [Security Reviewer](https://msxorg.github.io/docs/Agents/security-reviewer/) — a structured, defensive security pass. -- [Agent Author](https://msxorg.github.io/docs/Agents/agent-author/) — create and maintain these roles and pointers. +## Working with the ecosystem -## How work happens here - -- [Branching and Merging](https://msxorg.github.io/docs/Ways-of-Working/Branching-and-Merging/) and [Git Worktrees](https://msxorg.github.io/docs/Ways-of-Working/Git-Worktrees/) — the branch model and where to work. -- [Contribution Workflow](https://msxorg.github.io/docs/Ways-of-Working/Contribution-Workflow/) — the draft-first, Copilot-review loop through to a ready pull request. -- [Definition of Ready and Done](https://msxorg.github.io/docs/Ways-of-Working/Definition-of-Ready-and-Done/) — when a change is ready for review and when it lands. -- This repository's build and checks — see the [README](README.md). - -## The rule - -This file points; it never defines. Process knowledge lives in the docs and is referenced by canonical URL — never copied here. See [Agentic Development](https://msxorg.github.io/docs/Ways-of-Working/Agentic-Development/). +1. Get to know this repo first: + - [README](README.md) for what this repository is and how it builds. + - [CONTRIBUTING](CONTRIBUTING.md) for how to contribute and the review process. +2. Read the `.msx/main/docs` - start with the index to get an overview of what is here. +3. Read the `.msx/memory` - start with the index to get an overview of what is here. Use this while working - commit your memories here for work inside the PSModule organization. +4. While working with the code, do small micro commits and push on every commit. This will make it easier to review and merge your changes. diff --git a/src/docs/Capabilities/index.md b/src/docs/Capabilities/index.md index 91c8d0e..daab518 100644 --- a/src/docs/Capabilities/index.md +++ b/src/docs/Capabilities/index.md @@ -21,6 +21,7 @@ and design relate and evolve. | [Merge Automation](merge-automation/index.md) | How a pull request's required status checks become the machine-readable signal that drives automated approval and merge — green merges, red holds, nothing bypasses the gate. | | [Downstream Release Propagation](downstream-release-propagation/index.md) | How a release in one repository propagates to the repositories that depend on it, via a delegated agent pull request. | | [VS Code Extension Framework](vscode-extension-framework/index.md) | How a VS Code extension is built, tested, versioned, packaged, and published — one GitHub-native pipeline, opt-in from a template and a single settings file. | +| [PowerShell on GitHub](powershell-on-github/index.md) | How we make GitHub a first-class platform for PowerShell through reusable modules, actions, and capability gaps we close over time. | diff --git a/src/docs/Capabilities/powershell-on-github/design.md b/src/docs/Capabilities/powershell-on-github/design.md new file mode 100644 index 0000000..4b32bee --- /dev/null +++ b/src/docs/Capabilities/powershell-on-github/design.md @@ -0,0 +1,42 @@ +--- +title: Design +description: Architecture and implementation model for making GitHub PowerShell-native through modules, actions, and gap-closing workflows. +--- + +# Design + +## Capability model + +The model combines two tracks: + +- Build it: implement missing behavior using available GitHub and ecosystem APIs. +- Advocate it: document and escalate platform-native features that require vendor support. + +## Architecture components + +1. Module collection + - reusable PowerShell modules grouped by domain (language helpers, data formats, networking, security, API clients) +2. Automation collection + - reusable GitHub Actions for prepare, build, test, lint, document, publish, and release stages +3. Orchestration framework + - Process-PSModule pipeline to drive module lifecycle and release behavior +4. Parity gap backlog + - capability gaps mapped to either implementation or advocacy tracks + +## Operating pattern + +- Keep component-level details in initiative/module docs. +- Keep reusable architecture and decision rationale here. +- Link initiative pages to this capability as canonical context. + +## Current canonical references + +- PSModule initiative overview: ../../Initiatives/PSModule.md +- Process-PSModule framework: ../../Frameworks/Process-PSModule/index.md +- Coding standards baseline: ../../Coding-Standards/index.md + +## Planned evolution + +- Add a capability-level parity matrix with status per gap. +- Track implementation maturity for each build-it stream. +- Add explicit ownership and review cadence for advocacy items. diff --git a/src/docs/Capabilities/powershell-on-github/index.md b/src/docs/Capabilities/powershell-on-github/index.md new file mode 100644 index 0000000..7152ef5 --- /dev/null +++ b/src/docs/Capabilities/powershell-on-github/index.md @@ -0,0 +1,19 @@ +--- +title: PowerShell on GitHub +description: How we make GitHub a first-class platform for PowerShell through reusable modules, actions, and capability gaps we close over time. +--- + +# PowerShell on GitHub + +This capability captures the strategic and technical work of infusing GitHub with PowerShell. + +It centralizes reusable architecture and platform-gap documentation previously spread across initiative-local docs. + + + +| Page | Description | +| --- | --- | +| [Spec](spec.md) | Requirements and boundaries for PowerShell parity on GitHub using reusable modules, actions, and platform advocacy. | +| [Design](design.md) | Architecture and implementation model for making GitHub PowerShell-native through modules, actions, and gap-closing workflows. | + + diff --git a/src/docs/Capabilities/powershell-on-github/spec.md b/src/docs/Capabilities/powershell-on-github/spec.md new file mode 100644 index 0000000..b425f99 --- /dev/null +++ b/src/docs/Capabilities/powershell-on-github/spec.md @@ -0,0 +1,43 @@ +--- +title: Spec +description: Requirements and boundaries for PowerShell parity on GitHub using reusable modules, actions, and platform advocacy. +--- + +# Spec + +## Problem + +GitHub offers strong language-native experiences for mainstream ecosystems, but PowerShell still has capability gaps in dependency intelligence, security signals, publishing ergonomics, and first-party tooling support. + +## Goal + +Provide a PowerShell-first GitHub development experience that is easy, fast, and safe by default. + +## Requirements + +1. Reusable automation should be packaged as versioned, SHA-pinnable actions and modules. +2. Module and action delivery must be orchestrated through standardized CI/CD workflows. +3. Missing platform support should be addressed through either: + - build-it paths (when APIs exist) + - advocacy paths (when only platform vendors can close the gap) +4. Documentation for this capability must remain canonical in MSXOrg/docs. +5. Initiative repositories can reference this capability but not fork its canonical guidance. + +## Scope + +In scope: + +- module and action architecture for PowerShell on GitHub +- dependency, security, release, and publishing parity goals +- implementation patterns and inventory-level framing + +Out of scope: + +- module-specific operational docs +- repository-specific runbooks unrelated to reusable capability behavior + +## Success criteria + +- Capability guidance is discoverable under MSX capabilities. +- Initiative-local copies are replaced with pointers. +- PowerShell parity gaps are documented with a clear build-versus-advocate classification. diff --git a/src/docs/Initiatives/PSModule.md b/src/docs/Initiatives/PSModule.md index 909292f..b5eaf62 100644 --- a/src/docs/Initiatives/PSModule.md +++ b/src/docs/Initiatives/PSModule.md @@ -13,3 +13,13 @@ It is two things at once: - **The modules themselves** — a growing collection of reusable PowerShell modules built with that workflow. PSModule inherits the [Coding Standards](../Coding-Standards/index.md) and [Ways of Working](../Ways-of-Working/index.md) from this site and adds only what is specific to the framework. The end-to-end workflow that ships every module — Process-PSModule — is documented under [Frameworks](../Frameworks/Process-PSModule/index.md), and its module reference lives at [psmodule.io](https://psmodule.io). + +## Canonical boundary + +Cross-org standards and reusable architecture are canonical in MSXOrg/docs, including: + +- [Coding Standards](../Coding-Standards/index.md) +- [Capabilities](../Capabilities/index.md) +- [PowerShell on GitHub capability](../Capabilities/powershell-on-github/index.md) + +PSModule/docs is now intentionally scoped to module-specific operational details: module catalog pages, Process-PSModule repository anatomy, and template onboarding for module repositories. diff --git a/src/overrides/assets/javascripts/tablesort.js b/src/overrides/assets/javascripts/tablesort.js index 7922ebc..293ad46 100644 --- a/src/overrides/assets/javascripts/tablesort.js +++ b/src/overrides/assets/javascripts/tablesort.js @@ -1,29 +1,29 @@ /* global document$, Tablesort */ document$.subscribe(function () { - var tables = document.querySelectorAll("article table:not([class])"); - tables.forEach(function (table) { - // If table doesn't have a thead, create one from the first row - if (!table.querySelector("thead")) { - var firstRow = table.querySelector("tr"); - if (firstRow) { - var thead = document.createElement("thead"); - thead.appendChild(firstRow); - table.insertBefore(thead, table.firstChild); - } - } - new Tablesort(table); + var tables = document.querySelectorAll("article table:not([class])"); + tables.forEach(function (table) { + // If table doesn't have a thead, create one from the first row + if (!table.querySelector("thead")) { + var firstRow = table.querySelector("tr"); + if (firstRow) { + var thead = document.createElement("thead"); + thead.appendChild(firstRow); + table.insertBefore(thead, table.firstChild); + } + } + new Tablesort(table); - // Tablesort makes header cells focusable (tabindex=0) and sorts on click, - // but does not handle keyboard activation. Let Enter/Space sort too, so the - // sortable headers are usable without a mouse. Cover both th and td header - // cells, since a thead synthesized from the first row may hold td cells. - table.querySelectorAll("thead th, thead td").forEach(function (header) { - header.addEventListener("keydown", function (event) { - if (event.key === "Enter" || event.key === " ") { - event.preventDefault(); - header.click(); - } - }); - }); + // Tablesort makes header cells focusable (tabindex=0) and sorts on click, + // but does not handle keyboard activation. Let Enter/Space sort too, so the + // sortable headers are usable without a mouse. Cover both th and td header + // cells, since a thead synthesized from the first row may hold td cells. + table.querySelectorAll("thead th, thead td").forEach(function (header) { + header.addEventListener("keydown", function (event) { + if (event.key === "Enter" || event.key === " ") { + event.preventDefault(); + header.click(); + } + }); }); + }); }); diff --git a/src/overrides/assets/javascripts/tablesort.min.js b/src/overrides/assets/javascripts/tablesort.min.js index 65a83b1..1a9df7e 100644 --- a/src/overrides/assets/javascripts/tablesort.min.js +++ b/src/overrides/assets/javascripts/tablesort.min.js @@ -3,4 +3,4 @@ * http://tristen.ca/tablesort/demo/ * Copyright (c) 2021 ; Licensed MIT */ -!function(){function a(b,c){if(!(this instanceof a))return new a(b,c);if(!b||"TABLE"!==b.tagName)throw new Error("Element must be a table");this.init(b,c||{})}var b=[],c=function(a){var b;return window.CustomEvent&&"function"==typeof window.CustomEvent?b=new CustomEvent(a):(b=document.createEvent("CustomEvent"),b.initCustomEvent(a,!1,!1,void 0)),b},d=function(a,b){return a.getAttribute(b.sortAttribute||"data-sort")||a.textContent||a.innerText||""},e=function(a,b){return a=a.trim().toLowerCase(),b=b.trim().toLowerCase(),a===b?0:a0)if(a.tHead&&a.tHead.rows.length>0){for(e=0;e0&&n.push(m),o++;if(!n)return}for(o=0;o 0) if (a.tHead && a.tHead.rows.length > 0) { for (e = 0; e < a.tHead.rows.length; e++)if ("thead" === a.tHead.rows[e].getAttribute("data-sort-method")) { c = a.tHead.rows[e]; break } c || (c = a.tHead.rows[a.tHead.rows.length - 1]), g.thead = !0 } else c = a.rows[0]; if (c) { var h = function () { g.current && g.current !== this && g.current.removeAttribute("aria-sort"), g.current = this, g.sortTable(this) }; for (e = 0; e < c.cells.length; e++)f = c.cells[e], f.setAttribute("role", "columnheader"), "none" !== f.getAttribute("data-sort-method") && (f.tabindex = 0, f.addEventListener("click", h, !1), null !== f.getAttribute("data-sort-default") && (d = f)); d && (g.current = d, g.sortTable(d)) } }, sortTable: function (a, h) { var i = this, j = a.getAttribute("data-sort-column-key"), k = a.cellIndex, l = e, m = "", n = [], o = i.thead ? 0 : 1, p = a.getAttribute("data-sort-method"), q = a.getAttribute("aria-sort"); if (i.table.dispatchEvent(c("beforeSort")), h || (q = "ascending" === q ? "descending" : "descending" === q ? "ascending" : i.options.descending ? "descending" : "ascending", a.setAttribute("aria-sort", q)), !(i.table.rows.length < 2)) { if (!p) { for (var r; n.length < 3 && o < i.table.tBodies[0].rows.length;)r = j ? f(i.table.tBodies[0].rows[o].cells, j) : i.table.tBodies[0].rows[o].cells[k], m = r ? d(r, i.options) : "", m = m.trim(), m.length > 0 && n.push(m), o++; if (!n) return } for (o = 0; o < b.length; o++)if (m = b[o], p) { if (m.name === p) { l = m.sort; break } } else if (n.every(m.pattern)) { l = m.sort; break } for (i.col = k, o = 0; o < i.table.tBodies.length; o++) { var s, t = [], u = {}, v = 0, w = 0; if (!(i.table.tBodies[o].rows.length < 2)) { for (s = 0; s < i.table.tBodies[o].rows.length; s++) { var r; m = i.table.tBodies[o].rows[s], "none" === m.getAttribute("data-sort-method") ? u[v] = m : (r = j ? f(m.cells, j) : m.cells[i.col], t.push({ tr: m, td: r ? d(r, i.options) : "", index: v })), v++ } for ("descending" === q ? t.sort(g(l, !0)) : (t.sort(g(l, !1)), t.reverse()), s = 0; s < v; s++)u[s] ? (m = u[s], w++) : m = t[s - w].tr, i.table.tBodies[o].appendChild(m) } } i.table.dispatchEvent(c("afterSort")) } }, refresh: function () { void 0 !== this.current && this.sortTable(this.current, !0) } }, "undefined" != typeof module && module.exports ? module.exports = a : window.Tablesort = a }(); diff --git a/src/zensical.toml b/src/zensical.toml index e45e900..44b5fae 100644 --- a/src/zensical.toml +++ b/src/zensical.toml @@ -118,6 +118,11 @@ nav = [ {"Spec" = "Capabilities/vscode-extension-framework/spec.md"}, {"Design" = "Capabilities/vscode-extension-framework/design.md"}, ]}, + {"PowerShell on GitHub" = [ + "Capabilities/powershell-on-github/index.md", + {"Spec" = "Capabilities/powershell-on-github/spec.md"}, + {"Design" = "Capabilities/powershell-on-github/design.md"}, + ]}, ]}, {"Frameworks" = [ "Frameworks/index.md",