sdtk-ops-kit 0.3.0 → 0.3.3

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
@@ -5,7 +5,7 @@
5
5
  ## Package
6
6
 
7
7
  - Package: `sdtk-ops-kit`
8
- - Version in this source snapshot: `0.3.0`
8
+ - Version in this source snapshot: `0.3.3`
9
9
  - CLI: `sdtk-ops`
10
10
  - Latest published version lookup: `npm view sdtk-ops-kit version`
11
11
 
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "0.3.0",
2
+ "version": "0.3.3",
3
3
  "sourceCommit": "6896f2f26dfc5aee3f71751e869b80608e34ecb7",
4
4
  "fileCount": 44,
5
5
  "files": [
@@ -115,8 +115,8 @@
115
115
  },
116
116
  {
117
117
  "path": "toolkit/skills/ops-framer-deploy/scripts/framer-extract.mjs",
118
- "sha256": "76ea39d3cedf8c5ac8fede0c49b6807d1546e4934d673eae00b86120e9f268a1",
119
- "size": 12001
118
+ "sha256": "ff1ee39fbf002036b57b01ce110a1a40ebbe66696d5e180944079b64dd527a56",
119
+ "size": 15272
120
120
  },
121
121
  {
122
122
  "path": "toolkit/skills/ops-framer-deploy/scripts/framer-install.mjs",
@@ -135,8 +135,8 @@
135
135
  },
136
136
  {
137
137
  "path": "toolkit/skills/ops-framer-deploy/scripts/framer-verify.mjs",
138
- "sha256": "9da1f281c59f216238bf379afa43511340b03a7da99961ed5ff6d8f9ba5fcb06",
139
- "size": 7169
138
+ "sha256": "006780fa3c63acf78fb6c351aa7f879c51c1aabc828005534c3219309575ce17",
139
+ "size": 9624
140
140
  },
141
141
  {
142
142
  "path": "toolkit/skills/ops-framer-deploy/scripts/lib/config.mjs",
@@ -145,8 +145,8 @@
145
145
  },
146
146
  {
147
147
  "path": "toolkit/skills/ops-framer-deploy/SKILL.md",
148
- "sha256": "245e40f0afb5bc4973f149badc7c9b575865fc0fb85dc71a089f6acfba52791e",
149
- "size": 8470
148
+ "sha256": "bf6ef180b9361e3e5f19f9d296958405892fed6f825e2a8f6f18aa48f8704ffc",
149
+ "size": 14736
150
150
  },
151
151
  {
152
152
  "path": "toolkit/skills/ops-incident/references/communication-templates.md",
@@ -20,13 +20,13 @@ d5f58322afebcf5c3a110b02de0d2eec4494f9ed9d358b113b6717275c3524af toolkit/skills
20
20
  c2cacc94ffba4d7ef84e635c2078e08abb8d52f79afbbb1534661c0e0cf9bda6 toolkit/skills/ops-deploy/SKILL.md
21
21
  6f38c9b2ab972f272fb86e17926585a9a254a1c48c8454459a61315d4bd81d81 toolkit/skills/ops-discover/SKILL.md
22
22
  282645df98f039cbf8b1b29f52fe74b31c83790b1452240968e10a477947a884 toolkit/skills/ops-framer-deploy/framer-deploy.config.example.json
23
- 76ea39d3cedf8c5ac8fede0c49b6807d1546e4934d673eae00b86120e9f268a1 toolkit/skills/ops-framer-deploy/scripts/framer-extract.mjs
23
+ ff1ee39fbf002036b57b01ce110a1a40ebbe66696d5e180944079b64dd527a56 toolkit/skills/ops-framer-deploy/scripts/framer-extract.mjs
24
24
  ab50e9ce83a0aee4f7a41897f60fb71aea9ef96ef7f8dc0aa1e9ebe33af6dcee toolkit/skills/ops-framer-deploy/scripts/framer-install.mjs
25
25
  0f07f8fc469b06220e820b738a7d362323d96bf765055caf9255bc588d89b91f toolkit/skills/ops-framer-deploy/scripts/framer-place.mjs
26
26
  8ba082d86d92e8cf01168246264092b8543806dbc76bdf378863ce3f5955e2dc toolkit/skills/ops-framer-deploy/scripts/framer-scaffold.mjs
27
- 9da1f281c59f216238bf379afa43511340b03a7da99961ed5ff6d8f9ba5fcb06 toolkit/skills/ops-framer-deploy/scripts/framer-verify.mjs
27
+ 006780fa3c63acf78fb6c351aa7f879c51c1aabc828005534c3219309575ce17 toolkit/skills/ops-framer-deploy/scripts/framer-verify.mjs
28
28
  23f917c38b7772f792c38f91955faaf94c0f0b5b38b654a3b4a1da468a262ca3 toolkit/skills/ops-framer-deploy/scripts/lib/config.mjs
29
- 245e40f0afb5bc4973f149badc7c9b575865fc0fb85dc71a089f6acfba52791e toolkit/skills/ops-framer-deploy/SKILL.md
29
+ bf6ef180b9361e3e5f19f9d296958405892fed6f825e2a8f6f18aa48f8704ffc toolkit/skills/ops-framer-deploy/SKILL.md
30
30
  f6102d127e47861068b285ebbbb2045e4c3dc8cd9af73b3c975f285f2141639e toolkit/skills/ops-incident/references/communication-templates.md
31
31
  fda6d9cadc5a3757e5559798a67716a6356809735b076d47d6bd99a993b71b99 toolkit/skills/ops-incident/references/postmortem-template.md
32
32
  358644dcd477fe32d3368ced5c9da30663ae3d54fdd5e825ae3e56327f7f6f2d toolkit/skills/ops-incident/references/runbook-template.md
@@ -93,8 +93,67 @@ Each of these cost a live bug. They are the reason this skill exists as more tha
93
93
  | **Plugin data is node-scoped** | `framer.getPluginData` does not exist over a server connection, only `node.getPluginData`. Anchor the ledger on the home page. |
94
94
  | **Identity fields are plain properties** | `WebPageNode.path`, a breakpoint's `name`/`width` -- reading them via `getAttributes()` returns `undefined` with no error, so idempotency checks silently pass and everything gets created twice. |
95
95
  | **Framer injects `overflow` and `isolation` via `props.style`** | Both land on the component's own wrapper div. `overflow` clips `position:absolute` dropdowns and adds a scrollbar; `isolation: isolate` traps z-index so nothing can paint above a later instance. Force both back with `!important`. |
96
+ | **Components are server-rendered** | Framer runs the module on a server with no `window` and no `document`. Anything at module scope that touches either takes the page down — reported only on the published site's status panel, never by a browser-based check. |
97
+ | **A page frame is born fixed-height and white** | `createWebPage` gives a frame `height: 1080px` and a white background. Fixed height makes it *clip*, not grow: a 7668px page ships showing its first 1080px with no scrollbar. Set `height: "fit-content"` and the design's own ground colour on every breakpoint's frame. |
98
+ | **An instance freezes its sizing when it is created** | Framer reads the component's `@framerSupportedLayoutWidth` annotation *at instance-creation time*. Fixing the annotation afterwards does not resize instances already on a page — they keep the width baked in, even though the stored attribute still says `100%`. Re-place them. |
99
+ | **Plugin-data writes may not survive the session** | Measured twice: `setPluginData(key, null)` left the key and its old value; a later write read back correctly *inside the same connection* and had reverted when read from a fresh one. An editor session holding the project document is the likely writer. Never hand state between pipeline steps through plugin data — do upload, resolve and write in ONE connection. |
100
+ | **Uploading identical bytes returns the same asset** | Framer dedupes by content, so re-uploading an unchanged image costs nothing and creates no orphan. Only genuinely changed bytes make a new asset. |
96
101
  | **Editing a code file does not publish it** | `getUnpublishedPageChanges()` tracks page changes, not code edits, so it reports 0 while the live site still serves the old file. "Installed" and "live" are different states. |
97
102
 
103
+ ## The CSS the extractor cannot carry either
104
+
105
+ `rule.style.cssText` is CSSOM's *serialization*, and for one shape it is lossy in a way that errors nowhere. A shorthand whose value contains `var()`, whose longhands are then partly overridden inside the same rule, becomes a pending-substitution value that cannot be serialized:
106
+
107
+ ```css
108
+ .grad{ background: linear-gradient(100deg, var(--ink) 0%, var(--ink-fade) 100%);
109
+ background-clip: text; color: transparent; }
110
+ ```
111
+
112
+ serializes to `background-image: ; background-position-x: ; … background-clip: text; color: transparent;` — eight declarations with the value gone, which the parser then drops on re-parse. What ships is transparent text with nothing painted behind it.
113
+
114
+ The source page renders correctly throughout, because it uses the *parsed* rule. Only the shipped component is wrong. On the project this skill came from it put a missing word in the headline of four live pages, the homepage included, and survived a full review.
115
+
116
+ CSSOM will not hand the value back — `getPropertyValue()` on the shorthand returns `""` too — but **the author's text is still there**. These are inline `<style>` nodes, so `rule.parentStyleSheet.ownerNode.textContent` is the source CSS verbatim, `var()` references intact and still theme-switchable. `framer-extract.mjs` recovers the rule body from that.
117
+
118
+ Recovery is the fix; failing the run is the net under it, for the cases recovery cannot reach — a cross-origin or constructed sheet, a selector the matcher cannot find. Those abort the run and name the rule and its emptied properties.
119
+
120
+ (An earlier version of this skill asserted the value was unrecoverable and only failed. That was wrong: it read the *serialization* as the only source of truth and never looked at the sheet's own text.)
121
+
122
+ ## SSR: the module must import with no DOM
123
+
124
+ Framer server-renders code components. `window` and `document` do not exist there, and one top-level statement that reaches for either produces, on the published site:
125
+
126
+ ```
127
+ [error] One of your code files crashed while rendering on the server,
128
+ likely because it's reading something from window or document.
129
+ ReferenceError: document is not defined in code file <Component>.tsx
130
+ ```
131
+
132
+ The component renders perfectly in a browser, so geometry checks, screenshots and a local preview all pass. It surfaces only after the deploy, in the site's status panel.
133
+
134
+ This is the shape that causes it — browser code promoted to module scope, where `import` runs it:
135
+
136
+ ```js
137
+ var probe = document.createElement("canvas"); // top level: runs on import
138
+ window.SomeApi = { … }; // same
139
+ ```
140
+
141
+ It arrives most often by *unwrapping*: a `<script>` written as `(function (global) { … })(window)` is perfectly safe in a page, and stripping that wrapper to inline it into a component moves every statement in it to module scope at once.
142
+
143
+ The rules: DOM work belongs inside a function reached from `useEffect`, which the server never runs; a value that must be built from the DOM is built **lazily on first use**; and anything published onto `window` goes behind `typeof window !== "undefined"`. `framer-verify.mjs` evaluates each component's top-level statements in a context with neither global and fails the run on a `window`/`document` ReferenceError.
144
+
145
+ ## Replacing an asset in place
146
+
147
+ An asset ledger keyed by **name** cannot see that the bytes changed. Overwrite `hero.webp` with a new image, keep the filename, and the scaffold step skips it: the deploy reports success and the old image stays live. Nothing errors.
148
+
149
+ Either give the replacement a new name, or upload it and overwrite its ledger entry explicitly. Do not reach for a bulk `--reupload`: Framer has no delete-asset API, so every re-upload of an *unchanged* file that somehow differs leaves an orphan in the panel forever.
150
+
151
+ ## Wiring scripts must patch by narrow anchors
152
+
153
+ A wiring script that matches the component's **entire function body** as one exact string stops matching the first time the extractor's template changes — and then throws on every run. That is the intended fail-loud behaviour, but it is worth avoiding: anchor on the export line and a regex for the wrapper element instead, and the script survives template churn.
154
+
155
+ Two of these broke at once on the project this skill came from, and the second hid the first: the extractor had lost its `--page=` flag, so the page that fed the broken wiring script could not be re-extracted, so the script never ran to fail. When a flag is dropped, check what *else* silently stopped being exercised.
156
+
98
157
  ## Wiring: what extraction cannot carry
99
158
 
100
159
  `framer-extract.mjs` captures markup and CSS. It never captures JavaScript. Any section whose behaviour comes from a `<script>` -- a theme toggle, a tab group, a WebGL hero, a scroll-spy -- extracts as an inert copy that **looks** interactive.
@@ -111,6 +170,7 @@ Declare each page's wiring scripts in the config's `wire` array so the extractor
111
170
  | Check | Catches |
112
171
  |---|---|
113
172
  | `framer-verify.mjs` geometry | dropped CSS rules -- the component renders but is missing a colour, a grid, or a layout mode |
173
+ | `framer-verify.mjs` SSR import | DOM access at module scope, which crashes Framer's server render and is invisible to every browser-based check |
114
174
  | 404s treated as failures | an unresolved image, which also corrupts every measurement around it |
115
175
  | Framer's own `lintCode`/`typecheckCode` | code the project will not accept, regardless of what compiles locally |
116
176
  | Reading a file back from Framer | the difference between "the generator produced this" and "this is what shipped" |
@@ -102,6 +102,7 @@ const results = await page.evaluate(({ sections, assetExt }) => {
102
102
  }).join(", ");
103
103
 
104
104
  const matched = [];
105
+ const lossy = [];
105
106
  let tested = 0, kept = 0;
106
107
  const walk = (rules, into) => {
107
108
  for (const r of rules) {
@@ -117,7 +118,47 @@ const results = await page.evaluate(({ sections, assetExt }) => {
117
118
  const cls = (r.selectorText || "").match(/\.[A-Za-z_][-\w]*/g) || [];
118
119
  hit = cls.length > 0 && cls.every((c) => nodes.some((n) => n.classList && n.classList.contains(c.slice(1))));
119
120
  }
120
- if (hit) { kept++; into.push((viaAncestor ? "&" : scopeSel(r.selectorText)) + "{" + r.style.cssText + "}"); }
121
+ if (hit) {
122
+ kept++;
123
+ /* `r.style.cssText` is CSSOM's serialization, and it is LOSSY for one
124
+ shape: a shorthand whose value contains var() and whose longhands
125
+ are then partly overridden inside the same rule. The override makes
126
+ the shorthand unserializable, and the var()-bearing longhands are
127
+ pending-substitution values, which serialize as the EMPTY STRING:
128
+
129
+ .grad{ background: linear-gradient(..., var(--ink), ...);
130
+ background-clip: text; color: transparent; }
131
+
132
+ becomes `background-image: ; background-position-x: ; ...
133
+ background-clip: text; color: transparent;` -- eight declarations
134
+ the parser drops on the way back in, leaving transparent text with
135
+ nothing painted behind it. The SOURCE page renders fine (it uses
136
+ the parsed rule), so this is invisible until you look at what
137
+ shipped. It cost four live pages a missing word in the headline.
138
+
139
+ CSSOM will not hand the value back -- getPropertyValue() on the
140
+ shorthand returns "" too -- but the AUTHOR's text is still there:
141
+ these are inline <style> nodes, so ownerNode.textContent is the
142
+ source CSS verbatim, var() references intact and still
143
+ theme-switchable. So recover the rule body from that, and keep
144
+ failing the run only for the cases recovery cannot reach (a
145
+ cross-origin or constructed sheet, a selector the matcher cannot
146
+ find). Recovery is the fix; the failure is the net under it. */
147
+ const declBody = () => {
148
+ const decls = r.style.cssText;
149
+ if (!/([-\w]+):\s*(;|$)/.test(decls)) return decls;
150
+ const raw = r.parentStyleSheet?.ownerNode?.textContent;
151
+ if (raw) {
152
+ const sel = (r.selectorText || "").split(",").map((x) =>
153
+ x.trim().replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\s+/g, "\\s+")).join("\\s*,\\s*");
154
+ const m = raw.match(new RegExp("(?:^|[^-\\w.#%])" + sel + "\\s*\\{([^}]*)\\}"));
155
+ if (m) return m[1].trim();
156
+ }
157
+ lossy.push({ sel: r.selectorText, props: (decls.match(/[-\w]+(?=:\s*(?:;|$))/g) || []) });
158
+ return decls;
159
+ };
160
+ into.push((viaAncestor ? "&" : scopeSel(r.selectorText)) + "{" + declBody() + "}");
161
+ }
121
162
  } else if (r.type === CSSRule.MEDIA_RULE) {
122
163
  const inner = []; walk(r.cssRules, inner);
123
164
  if (inner.length) into.push("@media " + r.conditionText + "{" + inner.join("") + "}");
@@ -152,6 +193,7 @@ const results = await page.evaluate(({ sections, assetExt }) => {
152
193
  html: clone.outerHTML,
153
194
  css: matched.join("\n"),
154
195
  tokens,
196
+ lossy,
155
197
  stats: { elements: nodes.length, rulesTested: tested, rulesKept: kept,
156
198
  imgs: root.querySelectorAll("img").length, svgs: root.querySelectorAll("svg").length },
157
199
  });
@@ -246,6 +288,22 @@ export default function ${r.component}(props) {
246
288
  console.log(` ${r.component.padEnd(22)} ${String(r.stats.elements).padStart(4)} el ${String(r.stats.rulesKept).padStart(3)}/${String(r.stats.rulesTested).padEnd(4)} rules ${String(r.stats.imgs).padStart(2)} img ${String(r.stats.svgs).padStart(2)} svg ${kb.padStart(4)} KB`);
247
289
  }
248
290
 
291
+ /* Fail-closed, not a warning: a rule whose serialization lost its values ships
292
+ a component that looks almost right, which is the shape that survives review. */
293
+ const lossyRules = new Map();
294
+ for (const r of results) for (const l of r.lossy || []) {
295
+ if (!lossyRules.has(l.sel)) lossyRules.set(l.sel, new Set());
296
+ for (const prop of l.props) lossyRules.get(l.sel).add(prop);
297
+ }
298
+ if (lossyRules.size) {
299
+ console.log("\nFAIL CSSOM dropped declaration values while serializing these rules:");
300
+ for (const [sel, props] of lossyRules)
301
+ console.log(` ${sel} -> ${[...props].join(", ")} (emitted with empty values)`);
302
+ console.log(" Cause: a shorthand containing var() whose longhands are partly");
303
+ console.log(" overridden in the same rule. Rewrite it in the source CSS as longhands.");
304
+ failed++;
305
+ }
306
+
249
307
  console.log(`\n${results.length - failed} component(s) from ${pageFile} -> ${OUT}`);
250
308
  if (spec.wire?.length) console.log(`NEXT: this page declares wiring (${spec.wire.join(", ")}) -- run those now, or the behaviour they add is silently missing.`);
251
309
  process.exit(failed ? 1 : 0);
@@ -27,6 +27,7 @@
27
27
  import { chromium } from "playwright-core";
28
28
  import fs from "node:fs";
29
29
  import path from "node:path";
30
+ import vm from "node:vm";
30
31
  import { loadConfig, serveDir, resolveChrome } from "./lib/config.mjs";
31
32
 
32
33
  const arg = (n, d = null) => (process.argv.find((a) => a.startsWith(`--${n}=`)) || "").split("=").slice(1).join("=") || d;
@@ -134,5 +135,52 @@ for (const p of cfg.pages) {
134
135
 
135
136
  await browser.close();
136
137
  server.close();
138
+ /* ---------- SSR: the module must import with no DOM --------------------
139
+ *
140
+ * Framer server-renders code components. `window` and `document` do not exist
141
+ * there, and any top-level statement that reaches for them takes the whole
142
+ * page down with
143
+ *
144
+ * [error] One of your code files crashed while rendering on the server,
145
+ * likely because it's reading something from window or document.
146
+ *
147
+ * Geometry checks never see this: the component renders perfectly in a real
148
+ * browser, which is the only place they look. It shows up only on the
149
+ * published site's status panel, after the deploy.
150
+ *
151
+ * This is the shape that produces it -- browser code promoted to module scope,
152
+ * where an `import` runs it:
153
+ *
154
+ * var probe = document.createElement("canvas"); // top level: runs on import
155
+ * window.SomeApi = { ... }; // same
156
+ *
157
+ * DOM work belongs inside a function reached from useEffect, which the server
158
+ * never runs; a value that must be built from the DOM is built lazily on first
159
+ * use. Everything before the component's own definition is evaluated here in a
160
+ * context with neither global, which is what Framer's server does.
161
+ */
162
+ const stripImports = (src) => src.replace(/^import[^\n]*\n/gm, "");
163
+ let ssrFailed = 0, ssrChecked = 0;
164
+ for (const file of fs.readdirSync(COMPONENTS).filter((f) => f.endsWith(".tsx"))) {
165
+ const src = fs.readFileSync(path.join(COMPONENTS, file), "utf8");
166
+ const cut = src.search(/^export default function/m);
167
+ if (cut < 0) continue;
168
+ ssrChecked++;
169
+ const ctx = vm.createContext({ console: { log() {}, warn() {}, error() {} }, Math, Date, JSON, Promise, setTimeout, clearTimeout });
170
+ try {
171
+ new vm.Script(stripImports(src.slice(0, cut)), { filename: file }).runInContext(ctx, { timeout: 5000 });
172
+ } catch (e) {
173
+ // A ReferenceError for window/document is the real finding. Anything else
174
+ // is this harness meeting a browser global it did not stub, which is not
175
+ // what is being tested here.
176
+ if (e instanceof ReferenceError && /\b(window|document)\b/.test(e.message)) {
177
+ console.log(` SSR-FAIL ${file.padEnd(22)} ${e.message} at module scope -- would crash Framer's server render`);
178
+ ssrFailed++;
179
+ }
180
+ }
181
+ }
182
+ if (ssrChecked) console.log(ssrFailed ? `\n${ssrFailed} of ${ssrChecked} component(s) touch the DOM at import time` : `\nall ${ssrChecked} components import cleanly with no window/document`);
183
+ failed += ssrFailed;
184
+
137
185
  console.log(failed ? `\n${failed} of ${checked} component(s) failed` : `\nall ${checked} components render standalone at their page's own geometry`);
138
186
  process.exit(failed ? 1 : 0);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sdtk-ops-kit",
3
- "version": "0.3.0",
3
+ "version": "0.3.3",
4
4
  "description": "Skill-driven operations toolkit for deployment, verification, monitoring, incident response, backup, security, compliance, and cost discipline.",
5
5
  "bin": {
6
6
  "sdtk-ops": "bin/sdtk-ops.js"