@spfx-fast/spfx-workbench 0.1.3 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,8 +1,15 @@
1
1
  # SPFx Workbench
2
2
 
3
- An SPFx developer and agent workflow toolkit for local component preview, diagnostics, SharePoint API capture/replay, authentication-state reuse, and Heft debugging. It helps build and validate SPFx projects; it is not a security or credential scanner.
3
+ Build and debug SharePoint Framework (SPFx) components with a local preview, focused diagnostics, and tools for working with real SharePoint behavior. Workbench can replay captured API responses, reuse an existing browser storage state, and coordinate the project's Heft workflow.
4
4
 
5
- A local SharePoint Workbench-style page editor with a canvas, toolbox, and property pane. It supports SharePoint column layouts, responsive breakpoints, section emphasis, local section width presets, and a synthetic document-library web part. The consumer CLI can load a compatible React component or invoke a subset of SPFx web-part lifecycle hooks with explicit JSON properties and a narrow synthetic context. It does not create the SharePoint service scope or claim to reproduce the full SPFx host.
5
+ Start with the [IDE router](packages/ide/README.md) for the agent workflow, or install Workbench directly in an SPFx project:
6
+
7
+ ```sh
8
+ npm install --save-dev @spfx-fast/spfx-workbench
9
+ npx spfx-workbench --component src/components/HelloWorld.tsx
10
+ ```
11
+
12
+ The local canvas is a fast development aid, not a full SharePoint host. It renders compatible React components and a documented subset of SPFx lifecycle/context behavior; use the real SharePoint page when validating host integration. Workbench is a developer tool, not a security or credential scanner.
6
13
 
7
14
  ## Run locally
8
15
 
@@ -31,14 +38,14 @@ The portable `spfx-ide` skill ships in [`packages/ide/skills/spfx-ide/SKILL.md`]
31
38
 
32
39
  ## Preview a consumer component
33
40
 
34
- The npm package name is `@spfx-fast/spfx-workbench`. Version `0.1.2` is published; this checkout prepares public version `0.1.3`. Install the published package in an SPFx project and run the CLI from that project's root:
41
+ The npm package name is `@spfx-fast/spfx-workbench`. Install it in an SPFx project and run the CLI from that project's root:
35
42
 
36
43
  ```sh
37
44
  npm install --save-dev @spfx-fast/spfx-workbench
38
45
  npx spfx-workbench --component src/components/HelloWorld.tsx
39
46
  ```
40
47
 
41
- For contributors testing an unpublished checkout, install the repository path instead.
48
+ To test changes from this repository, install the local repository path instead.
42
49
 
43
50
  The registry install command is:
44
51
 
@@ -68,13 +75,13 @@ Inspect the consumer's installed runtime versions and an optional component entr
68
75
  npx spfx-workbench-doctor --component src/components/HelloWorld.tsx --props-file .spfx-workbench/preview-props.json
69
76
  ```
70
77
 
71
- The command emits JSON with per-check `supported`, `unsupported`, or `unknown` status plus mock coverage and provenance. For a props file, it reports the project-relative path and property names, never values, and flags a `context` override. It scans installed `@microsoft/sp-*` packages, including nested `node_modules`, requires every installed version to be SPFx 1.24+ and match `@microsoft/sp-core-library` exactly, and checks React and React DOM against 18.3.1. It also checks the current Node.js version against Microsoft's documented SPFx 1.24.1 compatibility: Node 22.14.0 or later within 22.x, 24.x, or 26.x. That check is `unknown` for other SPFx releases until their compatibility source is recorded. This is separate from the package's Vite engine range, which permits Node `^20.19.0 || >=22.12.0`; Node versions valid for Vite may still be unsupported by the consumer's Heft toolchain. Missing package metadata is `unknown` and summarized as incomplete. It does not test every SPFx behavior or infer component prop types/API usage.
78
+ The command emits JSON with per-check `supported`, `unsupported`, or `unknown` status plus mock coverage and provenance. For a props file, it reports the project-relative path and property names, never values, and flags a `context` override. It scans installed `@microsoft/sp-*` packages, including nested `node_modules`, accepts SPFx 1.x packages and reports package alignment separately. React 17 and 18 are recognized; other versions are flagged for review. Microsoft’s documented SPFx 1.24.1 Node.js range (22.14+ within 22.x, 24.x, or 26.x) is advisory and unknown for other releases. It never blocks Workbench on a consumer Node mismatch. Workbench itself requires Node `^20.19.0 || >=22.12.0` for Vite 8. The Heft launcher uses the consumer’s installed CLI without a version pin and applies to Heft-based SPFx projects (1.22+); older Gulp-era projects can use preview on a best-effort basis. Missing package metadata is `unknown` and summarized as incomplete. It does not test every SPFx behavior or infer component prop types/API usage.
72
79
 
73
80
  This is an early consumer-loader slice. It supports explicit JSON props and the documented read-only simulator context subset; it does not create full SPFx host context or infer an arbitrary TypeScript props contract. Broader SPFx compatibility checks and live SharePoint validation remain incomplete.
74
81
 
75
82
  ## How this fits with the SPFx Fast tools
76
83
 
77
- Use [`@spfx-fast/ide`](packages/ide/README.md) as the thin developer and agent entry point. Workbench 0.1.2 and IDE 0.1.2 are published. IDE 0.1.2 adds Workbench routes and automatic skill placement; the 0.1.1 npm publication attempt failed before the Trusted Publisher was corrected. This checkout prepares Workbench 0.1.3 and IDE 0.1.4. The `spfx-ide` CLI routes to focused tools; installation as a project devDependency or globally places Agent Skills guidance in supported skill directories unless lifecycle scripts are disabled. This confirms file placement, not discovery by every agent; check the agent's own skills list where available. Global CLI use also needs npm's global bin directory on `PATH`. Workbench owns component preview, synthetic context/API replay, diagnostics, capture, and Heft launch. The focused companion packages have separate jobs:
84
+ Use [`@spfx-fast/ide`](packages/ide/README.md) as the thin developer and agent entry point. The `spfx-ide` CLI routes to focused tools; installation as a project devDependency or globally places Agent Skills guidance in supported skill directories unless lifecycle scripts are disabled. This confirms file placement, not discovery by every agent; check the agent's own skills list where available. Global CLI use also needs npm's global bin directory on `PATH`. Workbench owns component preview, synthetic context/API replay, diagnostics, capture, and Heft launch. The focused companion packages have separate jobs:
78
85
 
79
86
  - [`@spfx-fast/playwright`](https://www.npmjs.com/package/%40spfx-fast/playwright) runs authenticated browser tests against a real SharePoint page.
80
87
  - [`@spfx-fast/knowledge`](https://www.npmjs.com/package/%40spfx-fast/knowledge) provides the SPFx agent skill and debugging references; use it to guide the tools, not as a runtime dependency.
@@ -192,7 +199,7 @@ Verify React Fast Refresh in a real browser with:
192
199
  npm run check:browser-hmr
193
200
  ```
194
201
 
195
- The check uses Playwright-managed Chromium, installed on first use, and does not require a system Chrome path. It edits a synthetic consumer component 20 times at a 1023 px viewport and confirms each React update applies, component state survives every edit, and the page does not navigate. It then adds an incompatible named export and confirms Vite reports the boundary reason, the browser reloads once, and the updated component appears. It reports min, median, p95, and max for compatible browser updates; it does not measure the full developer workflow or SharePoint. Set `--samples` to an integer from 1 to 100. `npm run check:responsive` additionally checks the five local section-width options with a synthetic web part at nine viewport widths and verifies the insertion control on touch input. `npm run check:release` runs the local gates, browser HMR check, and responsive layout check. It still does not start real Heft, establish tenant parity, or publish the package.
202
+ The check uses Playwright-managed Chromium, installed on first use, and does not require a system Chrome path. It edits a synthetic consumer component 20 times at a 1023 px viewport and confirms each React update applies, component state survives every edit, and the page does not navigate. It then adds an incompatible named export and confirms Vite reports the boundary reason, the browser reloads once, and the updated component appears. It reports min, median, p95, and max for compatible browser updates; it does not measure the full developer workflow or SharePoint. Set `--samples` to an integer from 1 to 100. `npm run check:responsive` additionally checks the five local section-width options with a synthetic web part at nine viewport widths and verifies the insertion control on touch input. `npm run check:release` runs the local gates, browser HMR check, and responsive layout check. It still does not start real Heft or establish tenant parity.
196
203
 
197
204
  Measure that endpoint while the dev server is running:
198
205
 
@@ -228,7 +235,7 @@ When the page is in edit mode during an SPFx debug session, the [SharePoint Fram
228
235
 
229
236
  ## Project status
230
237
 
231
- See [the engineering report](reports/sharepoint-simulator-engineering-report.html) for verified implementation, unmeasured baselines, known gaps, and release status. [Local section measurements](reports/section-layout-sizes.html) list the synthetic editor's section/web-part dimensions; [tenant page measurements](reports/tenant-page-layout-sizes.html) list read-only live view-mode section/ControlZone boxes at nine viewport widths.
238
+ See [the engineering report](reports/sharepoint-simulator-engineering-report.html) for implementation evidence, unmeasured baselines, and known gaps. [Local section measurements](reports/section-layout-sizes.html) list the synthetic editor's section/web-part dimensions; [tenant page measurements](reports/tenant-page-layout-sizes.html) list read-only live view-mode section/ControlZone boxes at nine viewport widths.
232
239
 
233
240
  Run the automated local release checks together with:
234
241
 
@@ -238,12 +245,12 @@ npm run check:local
238
245
 
239
246
  This builds the workbench, runs `npm test` (temporary-consumer regressions and a synthetic local-CDP auth capture check), measures 20 consumer Vite HMR events, and installs the clean npm tarball into a disposable consumer. It does not verify browser React apply/state retention; use `npm run check:release` for the additional Chrome gate. Neither command proves a real Heft session, live-page parity, or every release criterion below.
240
247
 
241
- Check the current npm tarball from a clean temporary consumer before changing release status:
248
+ Inspect the packed package in a clean temporary consumer:
242
249
 
243
250
  ```sh
244
251
  npm run check:tarball
245
252
  ```
246
253
 
247
- This packs the public-configured source manifest, checks every packed path against `package.json` `files`, requires consumer docs/fixtures/source and all declared binaries, verifies the MIT license matches the installed tarball and manifest, and checks that the Node.js engine range survives packing. It installs the package as a devDependency, checks each npm command shim, launches the packaged preview with a synthetic consumer component and props file, verifies the context wrapper, captured HAR response replay, and synthetic fallback, runs compact HAR diff through the installed capture command, and confirms tests, reports, captures, and specs are absent. Its JSON result includes the public package status, contents/license checks, packaged diff result, and install/time-to-first-usable-preview timings. The engineering report records setup timings against each artifact hash; these local warm-cache samples do not establish a general setup success rate or baseline comparison. It does not publish the package.
254
+ This packs the source manifest, checks every packed path against `package.json` `files`, requires consumer docs/fixtures/source and all declared binaries, verifies the MIT license matches the installed tarball and manifest, and checks that the Node.js engine range survives packing. It installs the package as a devDependency, checks each npm command shim, launches the packaged preview with a synthetic consumer component and props file, verifies the context wrapper, captured HAR response replay, and synthetic fallback, runs compact HAR diff through the installed capture command, and confirms tests, reports, captures, and specs are absent. Its JSON result includes package contents/license checks, packaged diff results, and install/time-to-first-usable-preview timings. The engineering report records setup timings against artifact hashes; these local warm-cache samples do not establish a general setup success rate or baseline comparison.
248
255
 
249
256
  Original simulator code is MIT licensed; see [LICENSE](LICENSE).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@spfx-fast/spfx-workbench",
3
- "version": "0.1.3",
3
+ "version": "0.1.5",
4
4
  "description": "Local SPFx component preview, diagnostics, SharePoint API capture and replay, and Heft debugging tools.",
5
5
  "publishConfig": {
6
6
  "access": "public"
@@ -68,10 +68,10 @@ function checkVersion(name, version, supported) {
68
68
  const match = /^(\d+)\.(\d+)\.(\d+)(?:\+.*)?$/.exec(version);
69
69
  if (!match) return { name, status: 'unknown', version, expected: supported };
70
70
  const [major, minor, patch] = match.slice(1).map(Number);
71
- const ok = name.startsWith('@microsoft/sp-')
72
- ? major === 1 && minor >= 24
73
- : major === 18 && minor === 3 && patch === 1;
74
- return { name, status: ok ? 'supported' : 'unsupported', version, expected: supported };
71
+ if (name.startsWith('@microsoft/sp-')) {
72
+ return { name, status: major === 1 ? 'supported' : 'unsupported', version, expected: supported };
73
+ }
74
+ return { name, status: major === 17 || major === 18 ? 'supported' : 'unknown', version, expected: supported };
75
75
  }
76
76
 
77
77
  async function diagnose() {
@@ -100,13 +100,13 @@ async function diagnose() {
100
100
  const results = [
101
101
  ...spfxPackages.map((name) => {
102
102
  const versions = spfxByName[name];
103
- const checks = versions.map((version) => checkVersion(name, version, 'SPFx 1.24 or newer'));
103
+ const checks = versions.map((version) => checkVersion(name, version, 'SPFx 1.x; Heft-based launcher applies from 1.22'));
104
104
  return {
105
105
  name,
106
106
  status: checks.length === 0 ? 'unknown' : checks.every((check) => check.status === 'supported') ? 'supported' : 'unsupported',
107
107
  version: versions.length === 1 ? versions[0] : null,
108
108
  versions,
109
- expected: 'SPFx 1.24 or newer',
109
+ expected: 'SPFx 1.x; Heft-based launcher applies from 1.22',
110
110
  };
111
111
  }),
112
112
  checkVersion('react', reactVersion, '18.3.1'),
@@ -126,12 +126,10 @@ async function diagnose() {
126
126
  ? 'unknown'
127
127
  : spfxByName['@microsoft/sp-webpart-base'].every((version) => version === '1.24.1')
128
128
  ? 'supported'
129
- : spfxByName['@microsoft/sp-webpart-base'].some((version) => checkVersion('@microsoft/sp-webpart-base', version, 'SPFx 1.24 or newer').status === 'unsupported')
130
- ? 'unsupported'
131
- : 'unknown',
129
+ : 'unknown',
132
130
  versions: spfxByName['@microsoft/sp-webpart-base'] ?? [],
133
131
  sourceVersion: MOCK_COVERAGE.context.version,
134
- expected: 'context declaration coverage is verified for SPFx 1.24.1; source review is required for other supported releases',
132
+ expected: 'context declaration coverage is verified for SPFx 1.24.1; source review is required for other releases',
135
133
  },
136
134
  ];
137
135
  if (componentArg) {
@@ -1,7 +1,7 @@
1
1
  const SOURCE = 'https://learn.microsoft.com/en-us/sharepoint/dev/spfx/set-up-your-development-environment';
2
2
  const EXPECTED = 'SPFx 1.24.1 supports Node.js 22.14.0 or later within 22.x, 24.x, and 26.x';
3
3
 
4
- /** Checks only the SPFx release for which the current Microsoft compatibility guidance is explicit. */
4
+ /** Reports Microsoft runtime guidance without blocking the local Workbench preview. */
5
5
  export function checkSPFxNodeRuntime(spfxVersion, nodeVersion) {
6
6
  const result = { name: 'spfx-node-runtime', spfxVersion: spfxVersion ?? null, nodeVersion: nodeVersion ?? null, expected: EXPECTED, source: SOURCE };
7
7
  if (spfxVersion !== '1.24.1') {
@@ -13,7 +13,7 @@ export function checkSPFxNodeRuntime(spfxVersion, nodeVersion) {
13
13
  const supported = (major === 22 && minor >= 14) || major === 24 || major === 26;
14
14
  return {
15
15
  ...result,
16
- status: supported ? 'supported' : 'unsupported',
17
- reason: supported ? 'The active Node.js major/minor is listed by Microsoft for SPFx 1.24.1.' : 'The active Node.js major/minor is not listed by Microsoft for SPFx 1.24.1.',
16
+ status: supported ? 'supported' : 'unknown',
17
+ reason: supported ? 'The active Node.js major/minor is listed by Microsoft for SPFx 1.24.1.' : 'The active Node.js major/minor is outside Microsoft’s listed range; this advisory does not block Workbench.',
18
18
  };
19
19
  }