sdtk-ops-kit 0.2.10 → 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 +2 -1
- package/assets/manifest/toolkit-bundle.manifest.json +51 -11
- package/assets/manifest/toolkit-bundle.sha256.txt +14 -6
- package/assets/toolkit/toolkit/AGENTS.md +1 -0
- package/assets/toolkit/toolkit/SDTKOPS_TOOLKIT.md +4 -2
- package/assets/toolkit/toolkit/scripts/install-claude-skills.ps1 +4 -4
- package/assets/toolkit/toolkit/scripts/install-codex-skills.ps1 +4 -4
- package/assets/toolkit/toolkit/scripts/uninstall-claude-skills.ps1 +2 -2
- package/assets/toolkit/toolkit/scripts/uninstall-codex-skills.ps1 +2 -2
- package/assets/toolkit/toolkit/skills/ops-framer-deploy/SKILL.md +189 -0
- package/assets/toolkit/toolkit/skills/ops-framer-deploy/framer-deploy.config.example.json +70 -0
- package/assets/toolkit/toolkit/skills/ops-framer-deploy/scripts/framer-extract.mjs +309 -0
- package/assets/toolkit/toolkit/skills/ops-framer-deploy/scripts/framer-install.mjs +96 -0
- package/assets/toolkit/toolkit/skills/ops-framer-deploy/scripts/framer-place.mjs +134 -0
- package/assets/toolkit/toolkit/skills/ops-framer-deploy/scripts/framer-scaffold.mjs +203 -0
- package/assets/toolkit/toolkit/skills/ops-framer-deploy/scripts/framer-verify.mjs +186 -0
- package/assets/toolkit/toolkit/skills/ops-framer-deploy/scripts/lib/config.mjs +163 -0
- package/package.json +1 -1
- package/src/lib/scope.js +1 -0
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.
|
|
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
|
|
|
@@ -159,6 +159,7 @@ Canonical journeys:
|
|
|
159
159
|
- incident: `ops-incident -> ops-debug -> ops-deploy` when rollback or corrective rollout is needed, then `ops-monitor -> ops-verify`
|
|
160
160
|
- monitoring: `ops-plan -> ops-monitor -> ops-verify`
|
|
161
161
|
- backup or recovery: `ops-plan -> ops-backup -> ops-verify`
|
|
162
|
+
- Framer template deploy: `ops-plan -> ops-framer-deploy -> ops-verify`
|
|
162
163
|
|
|
163
164
|
Always close work with `ops-verify`.
|
|
164
165
|
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
{
|
|
2
|
-
"version": "0.
|
|
3
|
-
"sourceCommit": "
|
|
4
|
-
"fileCount":
|
|
2
|
+
"version": "0.3.3",
|
|
3
|
+
"sourceCommit": "6896f2f26dfc5aee3f71751e869b80608e34ecb7",
|
|
4
|
+
"fileCount": 44,
|
|
5
5
|
"files": [
|
|
6
6
|
{
|
|
7
7
|
"path": "toolkit/AGENTS.md",
|
|
8
|
-
"sha256": "
|
|
9
|
-
"size":
|
|
8
|
+
"sha256": "77d09c309061991343ef7ae42181afb7b8f9684c74a3f3a10166c93dbcec6508",
|
|
9
|
+
"size": 16553
|
|
10
10
|
},
|
|
11
11
|
{
|
|
12
12
|
"path": "toolkit/install.ps1",
|
|
@@ -15,22 +15,22 @@
|
|
|
15
15
|
},
|
|
16
16
|
{
|
|
17
17
|
"path": "toolkit/scripts/install-claude-skills.ps1",
|
|
18
|
-
"sha256": "
|
|
18
|
+
"sha256": "53fddfb0424676929f72d844faa319f2e4eba9252f1c2c31fd8780c9a61f224a",
|
|
19
19
|
"size": 2474
|
|
20
20
|
},
|
|
21
21
|
{
|
|
22
22
|
"path": "toolkit/scripts/install-codex-skills.ps1",
|
|
23
|
-
"sha256": "
|
|
23
|
+
"sha256": "a3451bd0978790d2bca9eecce1f2ab79e9351c3e9ef4693d8e8e3f245db0d96f",
|
|
24
24
|
"size": 4761
|
|
25
25
|
},
|
|
26
26
|
{
|
|
27
27
|
"path": "toolkit/scripts/uninstall-claude-skills.ps1",
|
|
28
|
-
"sha256": "
|
|
28
|
+
"sha256": "61dd1e2c41cb7e09ef4e197c38989dc72a836bc663a40ddeeb099733f01261e3",
|
|
29
29
|
"size": 1901
|
|
30
30
|
},
|
|
31
31
|
{
|
|
32
32
|
"path": "toolkit/scripts/uninstall-codex-skills.ps1",
|
|
33
|
-
"sha256": "
|
|
33
|
+
"sha256": "092b5633861406e0e83fc62ecb261a678237197fd500933eb7a3d5915ed826e4",
|
|
34
34
|
"size": 2428
|
|
35
35
|
},
|
|
36
36
|
{
|
|
@@ -45,8 +45,8 @@
|
|
|
45
45
|
},
|
|
46
46
|
{
|
|
47
47
|
"path": "toolkit/SDTKOPS_TOOLKIT.md",
|
|
48
|
-
"sha256": "
|
|
49
|
-
"size":
|
|
48
|
+
"sha256": "3ad54f730fefdc94e5107a49b3d4a64e4169b035ceae90a4830d6f48944b2177",
|
|
49
|
+
"size": 8142
|
|
50
50
|
},
|
|
51
51
|
{
|
|
52
52
|
"path": "toolkit/skills/ops-backup/references/backup-script-patterns.md",
|
|
@@ -108,6 +108,46 @@
|
|
|
108
108
|
"sha256": "6f38c9b2ab972f272fb86e17926585a9a254a1c48c8454459a61315d4bd81d81",
|
|
109
109
|
"size": 5617
|
|
110
110
|
},
|
|
111
|
+
{
|
|
112
|
+
"path": "toolkit/skills/ops-framer-deploy/framer-deploy.config.example.json",
|
|
113
|
+
"sha256": "282645df98f039cbf8b1b29f52fe74b31c83790b1452240968e10a477947a884",
|
|
114
|
+
"size": 4410
|
|
115
|
+
},
|
|
116
|
+
{
|
|
117
|
+
"path": "toolkit/skills/ops-framer-deploy/scripts/framer-extract.mjs",
|
|
118
|
+
"sha256": "ff1ee39fbf002036b57b01ce110a1a40ebbe66696d5e180944079b64dd527a56",
|
|
119
|
+
"size": 15272
|
|
120
|
+
},
|
|
121
|
+
{
|
|
122
|
+
"path": "toolkit/skills/ops-framer-deploy/scripts/framer-install.mjs",
|
|
123
|
+
"sha256": "ab50e9ce83a0aee4f7a41897f60fb71aea9ef96ef7f8dc0aa1e9ebe33af6dcee",
|
|
124
|
+
"size": 4846
|
|
125
|
+
},
|
|
126
|
+
{
|
|
127
|
+
"path": "toolkit/skills/ops-framer-deploy/scripts/framer-place.mjs",
|
|
128
|
+
"sha256": "0f07f8fc469b06220e820b738a7d362323d96bf765055caf9255bc588d89b91f",
|
|
129
|
+
"size": 6876
|
|
130
|
+
},
|
|
131
|
+
{
|
|
132
|
+
"path": "toolkit/skills/ops-framer-deploy/scripts/framer-scaffold.mjs",
|
|
133
|
+
"sha256": "8ba082d86d92e8cf01168246264092b8543806dbc76bdf378863ce3f5955e2dc",
|
|
134
|
+
"size": 10263
|
|
135
|
+
},
|
|
136
|
+
{
|
|
137
|
+
"path": "toolkit/skills/ops-framer-deploy/scripts/framer-verify.mjs",
|
|
138
|
+
"sha256": "006780fa3c63acf78fb6c351aa7f879c51c1aabc828005534c3219309575ce17",
|
|
139
|
+
"size": 9624
|
|
140
|
+
},
|
|
141
|
+
{
|
|
142
|
+
"path": "toolkit/skills/ops-framer-deploy/scripts/lib/config.mjs",
|
|
143
|
+
"sha256": "23f917c38b7772f792c38f91955faaf94c0f0b5b38b654a3b4a1da468a262ca3",
|
|
144
|
+
"size": 7293
|
|
145
|
+
},
|
|
146
|
+
{
|
|
147
|
+
"path": "toolkit/skills/ops-framer-deploy/SKILL.md",
|
|
148
|
+
"sha256": "bf6ef180b9361e3e5f19f9d296958405892fed6f825e2a8f6f18aa48f8704ffc",
|
|
149
|
+
"size": 14736
|
|
150
|
+
},
|
|
111
151
|
{
|
|
112
152
|
"path": "toolkit/skills/ops-incident/references/communication-templates.md",
|
|
113
153
|
"sha256": "f6102d127e47861068b285ebbbb2045e4c3dc8cd9af73b3c975f285f2141639e",
|
|
@@ -1,12 +1,12 @@
|
|
|
1
|
-
|
|
1
|
+
77d09c309061991343ef7ae42181afb7b8f9684c74a3f3a10166c93dbcec6508 toolkit/AGENTS.md
|
|
2
2
|
e79e1ab404abf83a4f90838a2f6450c387ada7e65b137a18f70f0cab74fc14f0 toolkit/install.ps1
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
3
|
+
53fddfb0424676929f72d844faa319f2e4eba9252f1c2c31fd8780c9a61f224a toolkit/scripts/install-claude-skills.ps1
|
|
4
|
+
a3451bd0978790d2bca9eecce1f2ab79e9351c3e9ef4693d8e8e3f245db0d96f toolkit/scripts/install-codex-skills.ps1
|
|
5
|
+
61dd1e2c41cb7e09ef4e197c38989dc72a836bc663a40ddeeb099733f01261e3 toolkit/scripts/uninstall-claude-skills.ps1
|
|
6
|
+
092b5633861406e0e83fc62ecb261a678237197fd500933eb7a3d5915ed826e4 toolkit/scripts/uninstall-codex-skills.ps1
|
|
7
7
|
712382d838a18b6cc6a5285b3c536fac74138c752a3fa1fd318828b19ece6b8f toolkit/sdtk-spec.config.json
|
|
8
8
|
2a306c1609499fb4910b86d5ec6e8c796e0cdf72c5f97fe3df9c1388ac62b913 toolkit/sdtk-spec.config.profiles.example.json
|
|
9
|
-
|
|
9
|
+
3ad54f730fefdc94e5107a49b3d4a64e4169b035ceae90a4830d6f48944b2177 toolkit/SDTKOPS_TOOLKIT.md
|
|
10
10
|
1cd81e12cebdb2be528803e2d8afe43959aab1493e55499af529b99ec566a56c toolkit/skills/ops-backup/references/backup-script-patterns.md
|
|
11
11
|
76e8385190d967bf98b3cafbbf8925d9b9c656ee7a7ed66ff51285b6459ebff1 toolkit/skills/ops-backup/SKILL.md
|
|
12
12
|
d27e47b0c832656c2835e3d3e32dae7c86419014199439b10fc6823956324716 toolkit/skills/ops-ci-cd/references/pipeline-examples.md
|
|
@@ -19,6 +19,14 @@ d70b59d276edf5c6c8aebb5fc669b8f6d04673fc8e8561cbaf4d7e5fb9f4e2f2 toolkit/skills
|
|
|
19
19
|
d5f58322afebcf5c3a110b02de0d2eec4494f9ed9d358b113b6717275c3524af toolkit/skills/ops-debug/SKILL.md
|
|
20
20
|
c2cacc94ffba4d7ef84e635c2078e08abb8d52f79afbbb1534661c0e0cf9bda6 toolkit/skills/ops-deploy/SKILL.md
|
|
21
21
|
6f38c9b2ab972f272fb86e17926585a9a254a1c48c8454459a61315d4bd81d81 toolkit/skills/ops-discover/SKILL.md
|
|
22
|
+
282645df98f039cbf8b1b29f52fe74b31c83790b1452240968e10a477947a884 toolkit/skills/ops-framer-deploy/framer-deploy.config.example.json
|
|
23
|
+
ff1ee39fbf002036b57b01ce110a1a40ebbe66696d5e180944079b64dd527a56 toolkit/skills/ops-framer-deploy/scripts/framer-extract.mjs
|
|
24
|
+
ab50e9ce83a0aee4f7a41897f60fb71aea9ef96ef7f8dc0aa1e9ebe33af6dcee toolkit/skills/ops-framer-deploy/scripts/framer-install.mjs
|
|
25
|
+
0f07f8fc469b06220e820b738a7d362323d96bf765055caf9255bc588d89b91f toolkit/skills/ops-framer-deploy/scripts/framer-place.mjs
|
|
26
|
+
8ba082d86d92e8cf01168246264092b8543806dbc76bdf378863ce3f5955e2dc toolkit/skills/ops-framer-deploy/scripts/framer-scaffold.mjs
|
|
27
|
+
006780fa3c63acf78fb6c351aa7f879c51c1aabc828005534c3219309575ce17 toolkit/skills/ops-framer-deploy/scripts/framer-verify.mjs
|
|
28
|
+
23f917c38b7772f792c38f91955faaf94c0f0b5b38b654a3b4a1da468a262ca3 toolkit/skills/ops-framer-deploy/scripts/lib/config.mjs
|
|
29
|
+
bf6ef180b9361e3e5f19f9d296958405892fed6f825e2a8f6f18aa48f8704ffc toolkit/skills/ops-framer-deploy/SKILL.md
|
|
22
30
|
f6102d127e47861068b285ebbbb2045e4c3dc8cd9af73b3c975f285f2141639e toolkit/skills/ops-incident/references/communication-templates.md
|
|
23
31
|
fda6d9cadc5a3757e5559798a67716a6356809735b076d47d6bd99a993b71b99 toolkit/skills/ops-incident/references/postmortem-template.md
|
|
24
32
|
358644dcd477fe32d3368ced5c9da30663ae3d54fdd5e825ae3e56327f7f6f2d toolkit/skills/ops-incident/references/runbook-template.md
|
|
@@ -166,6 +166,7 @@ Use the suite products according to task intent:
|
|
|
166
166
|
- CI/CD changes
|
|
167
167
|
- monitoring, incident response, security-infra, backup, compliance
|
|
168
168
|
- entry: `ops-discover` (when boundary is unclear), `ops-plan`, `ops-deploy`, `ops-incident`, `ops-monitor`, `ops-backup`, `ops-verify`, `ops-debug`
|
|
169
|
+
- vendor-specific: `ops-framer-deploy` when the deploy target is a Framer project
|
|
169
170
|
|
|
170
171
|
Cross-cutting capabilities (not a linear lane; usable across every phase):
|
|
171
172
|
|
|
@@ -33,7 +33,7 @@ The current public package is:
|
|
|
33
33
|
- Latest published version lookup: `npm view sdtk-ops-kit version`
|
|
34
34
|
|
|
35
35
|
The truthful current operational surface after `init` is skill-driven:
|
|
36
|
-
- the
|
|
36
|
+
- the 16 `ops-*` skills remain the real operating surface
|
|
37
37
|
- `ops-discover` remains a skill, not a CLI command
|
|
38
38
|
- `ops-verify` remains the required closing skill for every canonical journey
|
|
39
39
|
- `generate` remains unsupported and deferred
|
|
@@ -138,6 +138,7 @@ Other valid but non-primary routed skills in this wave:
|
|
|
138
138
|
| `ops-deploy` | execute deployments with health gates, rollout strategy, and rollback discipline |
|
|
139
139
|
| `ops-container` | define secure image build and container orchestration patterns |
|
|
140
140
|
| `ops-ci-cd` | build and manage pipelines, promotion flow, artifact handling, and secret controls |
|
|
141
|
+
| `ops-framer-deploy` | deploy a built HTML template into a Framer project as code components |
|
|
141
142
|
|
|
142
143
|
### 5.3 Operations
|
|
143
144
|
|
|
@@ -195,7 +196,8 @@ Use these documents by role:
|
|
|
195
196
|
|
|
196
197
|
## 8. Scope
|
|
197
198
|
|
|
198
|
-
`SDTK-OPS` v1 contains 15 core skills
|
|
199
|
+
`SDTK-OPS` v1 contains 15 cloud-agnostic core skills, plus `ops-framer-deploy`,
|
|
200
|
+
the one vendor-specific skill in the set (Framer Server API).
|
|
199
201
|
|
|
200
202
|
Not part of the current supported wave:
|
|
201
203
|
- provider-specific packs such as AWS, GCP, or Azure variants
|
|
@@ -16,8 +16,8 @@ if (-not (Test-Path -LiteralPath $skillsSource)) {
|
|
|
16
16
|
}
|
|
17
17
|
|
|
18
18
|
$managedSkills = @(Get-ChildItem -LiteralPath $skillsSource -Directory | Sort-Object Name)
|
|
19
|
-
if ($managedSkills.Count -ne
|
|
20
|
-
throw "Expected
|
|
19
|
+
if ($managedSkills.Count -ne 16) {
|
|
20
|
+
throw "Expected 16 managed SDTK-OPS skills but found $($managedSkills.Count)."
|
|
21
21
|
}
|
|
22
22
|
|
|
23
23
|
if ($Scope -eq 'user') {
|
|
@@ -67,8 +67,8 @@ $installedNow = @(
|
|
|
67
67
|
Where-Object { $managedSkills.Name -contains $_.Name } |
|
|
68
68
|
Select-Object -ExpandProperty Name
|
|
69
69
|
)
|
|
70
|
-
if ($installedNow.Count -ne
|
|
71
|
-
throw "Claude skill install incomplete. Expected
|
|
70
|
+
if ($installedNow.Count -ne 16) {
|
|
71
|
+
throw "Claude skill install incomplete. Expected 16 managed skills at $skillsDest but found $($installedNow.Count)."
|
|
72
72
|
}
|
|
73
73
|
|
|
74
74
|
if (-not $Quiet) {
|
|
@@ -81,8 +81,8 @@ if (-not (Test-Path -LiteralPath $skillsSource)) {
|
|
|
81
81
|
}
|
|
82
82
|
|
|
83
83
|
$managedSkills = @(Get-ChildItem -LiteralPath $skillsSource -Directory | Sort-Object Name)
|
|
84
|
-
if ($managedSkills.Count -ne
|
|
85
|
-
throw "Expected
|
|
84
|
+
if ($managedSkills.Count -ne 16) {
|
|
85
|
+
throw "Expected 16 managed SDTK-OPS skills but found $($managedSkills.Count)."
|
|
86
86
|
}
|
|
87
87
|
|
|
88
88
|
$codexHome = Resolve-CodexHome -TargetScope $Scope -TargetProjectPath $ProjectPath
|
|
@@ -132,8 +132,8 @@ $installedNow = @(
|
|
|
132
132
|
Where-Object { $expectedNames -contains $_.Name } |
|
|
133
133
|
Select-Object -ExpandProperty Name
|
|
134
134
|
)
|
|
135
|
-
if ($installedNow.Count -ne
|
|
136
|
-
throw "Codex skill install incomplete. Expected
|
|
135
|
+
if ($installedNow.Count -ne 16) {
|
|
136
|
+
throw "Codex skill install incomplete. Expected 16 managed skills at $skillsDest but found $($installedNow.Count)."
|
|
137
137
|
}
|
|
138
138
|
|
|
139
139
|
if (-not $Quiet) {
|
|
@@ -18,8 +18,8 @@ if (-not (Test-Path -LiteralPath $skillsSource)) {
|
|
|
18
18
|
$managedSkillNames = @(
|
|
19
19
|
Get-ChildItem -LiteralPath $skillsSource -Directory | Sort-Object Name | Select-Object -ExpandProperty Name
|
|
20
20
|
)
|
|
21
|
-
if ($managedSkillNames.Count -ne
|
|
22
|
-
throw "Expected
|
|
21
|
+
if ($managedSkillNames.Count -ne 16) {
|
|
22
|
+
throw "Expected 16 managed SDTK-OPS skills but found $($managedSkillNames.Count)."
|
|
23
23
|
}
|
|
24
24
|
|
|
25
25
|
if ($Scope -eq 'user') {
|
|
@@ -43,8 +43,8 @@ $managedSkillNames = @(
|
|
|
43
43
|
Sort-Object Name |
|
|
44
44
|
ForEach-Object { "sdtk-$($_.Name)" }
|
|
45
45
|
)
|
|
46
|
-
if ($managedSkillNames.Count -ne
|
|
47
|
-
throw "Expected
|
|
46
|
+
if ($managedSkillNames.Count -ne 16) {
|
|
47
|
+
throw "Expected 16 managed SDTK-OPS skills but found $($managedSkillNames.Count)."
|
|
48
48
|
}
|
|
49
49
|
|
|
50
50
|
$codexHome = Resolve-CodexHome -TargetScope $Scope -TargetProjectPath $ProjectPath
|
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ops-framer-deploy
|
|
3
|
+
description: Deploy an HTML template to Framer as code components. Use when shipping a built static site into a Framer project -- covers project scaffolding, section-to-component extraction, asset ledgering, instance placement, and the Framer API constraints that are not in its docs.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Ops Framer Deploy
|
|
7
|
+
|
|
8
|
+
## Overview
|
|
9
|
+
|
|
10
|
+
Framer marketplace templates are Framer projects, not HTML. A site that already exists as built HTML has to be moved into Framer's own model, and the naive route -- rebuilding it by hand on the canvas -- both loses fidelity and cannot be repeated.
|
|
11
|
+
|
|
12
|
+
This skill ships the pipeline that does it by script instead: build once, extract sections into code components, upload assets with a URL ledger, install, place instances in document order, publish. Everything except publishing is automated.
|
|
13
|
+
|
|
14
|
+
## The Iron Law
|
|
15
|
+
|
|
16
|
+
```
|
|
17
|
+
NOTHING SHIPS TO FRAMER THAT HAS NOT BEEN RENDERED AND MEASURED FIRST
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Every failure this skill documents shared one shape: **no error, plausible-looking output, wrong result.** Reading generated code never caught any of them. Rendering it did.
|
|
21
|
+
|
|
22
|
+
## When to Use
|
|
23
|
+
|
|
24
|
+
Use for:
|
|
25
|
+
- moving a built HTML site into a Framer project
|
|
26
|
+
- keeping a Framer edition in sync with an HTML source that keeps changing
|
|
27
|
+
- template work destined for the Framer marketplace
|
|
28
|
+
|
|
29
|
+
Do not use for:
|
|
30
|
+
- designing a page inside Framer from scratch (no API reaches that)
|
|
31
|
+
- sites whose value is Framer-native components a buyer will edit on canvas
|
|
32
|
+
|
|
33
|
+
## Prerequisites
|
|
34
|
+
|
|
35
|
+
`~/.sdtk/framer.env`, chmod 600, never in the repo and never on argv:
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
FRAMER_API_KEY=<key>
|
|
39
|
+
FRAMER_PROJECT_URL=https://framer.com/projects/<name>--<id>
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`framer-api` (pin the version you verified against) and `playwright-core` with a Chromium available.
|
|
43
|
+
|
|
44
|
+
## Pipeline
|
|
45
|
+
|
|
46
|
+
```
|
|
47
|
+
build HTML -> framer-scaffold -> framer-extract -> [wire-*] -> framer-verify
|
|
48
|
+
|
|
|
49
|
+
framer-install <-----------+
|
|
50
|
+
|
|
|
51
|
+
framer-place
|
|
52
|
+
|
|
|
53
|
+
Publish (Framer editor, manual)
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
cp framer-deploy.config.example.json framer-deploy.config.json # then edit
|
|
58
|
+
node framer-scaffold.mjs --apply # pages, breakpoints, styles, assets
|
|
59
|
+
node framer-extract.mjs --page=index.html # sections -> components/
|
|
60
|
+
node wire-*.mjs # re-apply any JS behaviour (see below)
|
|
61
|
+
node framer-verify.mjs # render each one, compare to its page
|
|
62
|
+
node framer-install.mjs --apply # upload + Framer's own lint/typecheck
|
|
63
|
+
node framer-place.mjs --apply # instances onto pages, in order
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Order matters and is not cosmetic: each `wire-*.mjs` patches what the extractor just wrote, so re-extracting without re-running them silently reverts those components to inert.
|
|
67
|
+
|
|
68
|
+
## <HARD-GATE> Before install
|
|
69
|
+
|
|
70
|
+
Do not run `framer-install.mjs --apply` unless all are true:
|
|
71
|
+
- `framer-verify.mjs` passes, or every exceedance is a per-component tolerance with a screenshot-confirmed cause
|
|
72
|
+
- every asset marker resolves (the installer refuses unresolved markers -- do not work around it)
|
|
73
|
+
- components carrying JS behaviour have had their wiring script re-run since the last extraction
|
|
74
|
+
|
|
75
|
+
## <HARD-GATE> Before publish
|
|
76
|
+
|
|
77
|
+
- read one installed file's content back FROM FRAMER (`getCodeFiles()` -> `content`) and confirm what you think you shipped is what is there
|
|
78
|
+
- confirm no unresolved markers, no leftover placeholder tokens
|
|
79
|
+
- Framer's lint + typecheck clean on every file
|
|
80
|
+
|
|
81
|
+
## Framer API constraints that are not in the docs
|
|
82
|
+
|
|
83
|
+
Each of these cost a live bug. They are the reason this skill exists as more than a script folder.
|
|
84
|
+
|
|
85
|
+
| Constraint | What happens if you do not know it |
|
|
86
|
+
|---|---|
|
|
87
|
+
| **Agent API is unreachable over a server connection** | `startAgentConversation` and siblings exist in the SDK types (shared with the in-editor plugin runtime) but none are exposed to `connect(url, key)`. There is no "describe the page and Framer builds it" path. |
|
|
88
|
+
| **`parentId` only resolves same-session nodes** (`@alpha`) | A frame read back from a pre-existing page is rejected with "Parent node not found", is not returned by `getNode()`, and enumerating frames first does not help. Re-create empty pages in-session before placing. |
|
|
89
|
+
| **Breakpoints inherit from the base frame** | Placing per breakpoint yields N copies of everything. Place into the base only. |
|
|
90
|
+
| **`uploadImage` rejects AVIF** | Fails through every input shape the SDK accepts, while the identical WebP uploads first try. |
|
|
91
|
+
| **No endpoint lists image assets** | `getImage`/`getImageData` need a node already using the image. The upload-time URL is the only record -- keep a ledger or lose them. |
|
|
92
|
+
| **`setPluginData` caps a value at 2 kB** | One JSON blob of ~40 asset URLs exceeds it mid-write. Use one key per image. |
|
|
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
|
+
| **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
|
+
| **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. |
|
|
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. |
|
|
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
|
+
|
|
157
|
+
## Wiring: what extraction cannot carry
|
|
158
|
+
|
|
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.
|
|
160
|
+
|
|
161
|
+
Write one `wire-<component>.mjs` per such component. It re-reads the generated file and rewrites the component body to add the behaviour in a `useEffect`, torn down in the effect's cleanup. Two rules:
|
|
162
|
+
|
|
163
|
+
- **Scope every query to the component's own root**, never `document.getElementById`. Two instances on one page otherwise collide, and a document-wide `querySelectorAll` reaches into other components.
|
|
164
|
+
- **A control that does nothing is worse than no control.** A button that looks clickable and is inert reads as broken and survives review, because nothing errors.
|
|
165
|
+
|
|
166
|
+
Declare each page's wiring scripts in the config's `wire` array so the extractor prints the reminder.
|
|
167
|
+
|
|
168
|
+
## Verification, and what each check is for
|
|
169
|
+
|
|
170
|
+
| Check | Catches |
|
|
171
|
+
|---|---|
|
|
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 |
|
|
174
|
+
| 404s treated as failures | an unresolved image, which also corrupts every measurement around it |
|
|
175
|
+
| Framer's own `lintCode`/`typecheckCode` | code the project will not accept, regardless of what compiles locally |
|
|
176
|
+
| Reading a file back from Framer | the difference between "the generator produced this" and "this is what shipped" |
|
|
177
|
+
|
|
178
|
+
Widen a per-component tolerance only with a cause you confirmed by screenshot. The legitimate one: a page embedding a local variable font Framer cannot serve, so the component substitutes a hosted family whose letterforms are a different width, and text reflows. That is what shipping looks like, not a regression.
|
|
179
|
+
|
|
180
|
+
## <HARD-GATE> Do not
|
|
181
|
+
|
|
182
|
+
- do not hand-edit generated `components/*.tsx` -- the next extraction overwrites it
|
|
183
|
+
- do not put the API key on argv, in the repo, or in a log line
|
|
184
|
+
- do not run `framer-place.mjs --replace` against a page someone arranged by hand; the unflagged run already skips any page with content, and that guard is the only thing standing between a script and someone's layout
|
|
185
|
+
- do not claim the site is updated because a script said "installed" -- publishing is a separate, manual action
|
|
186
|
+
|
|
187
|
+
## Handoff
|
|
188
|
+
|
|
189
|
+
Report with: components installed and their lint/typecheck state, verify results with real numbers (not "passed"), what was read back from Framer, and explicitly whether the site has been published or only installed.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$comment": "Copy to framer-deploy.config.json next to your built site and edit. Every path is resolved relative to THIS file. Nothing project-specific lives in the scripts.",
|
|
3
|
+
|
|
4
|
+
"projectName": "my-template",
|
|
5
|
+
|
|
6
|
+
"buildDir": "./out",
|
|
7
|
+
"serveRoot": "./",
|
|
8
|
+
"outDir": "./framer/components",
|
|
9
|
+
|
|
10
|
+
"$comment_ledger": "Prefix for the per-image plugin-data keys recording uploaded asset URLs. Unique per project inside one Framer project. Changing it later orphans the ledger and forces a re-upload -- it is the only record of those URLs, since Framer has no list-images endpoint.",
|
|
11
|
+
"ledgerPrefix": "mytemplate.asset.",
|
|
12
|
+
|
|
13
|
+
"$comment_assets": "Framer's uploader REJECTS AVIF. Point this at .webp even if the site ships AVIF first for real browsers; Framer re-optimises on publish.",
|
|
14
|
+
"assetDirs": ["./out/assets", "./out/assets/thumbs"],
|
|
15
|
+
"assetExtension": ".webp",
|
|
16
|
+
|
|
17
|
+
"$comment_tokens": "Colour styles are parsed from this file, never retyped. themes.dark is the block your CSS treats as default; themes.light is the opt-in one. Framer requires `light` and treats `dark` as optional, so a dark-default site maps light <- its day block.",
|
|
18
|
+
"tokensFile": "./src/tokens.css",
|
|
19
|
+
"themes": { "dark": ":root", "light": "[data-theme=\"day\"]" },
|
|
20
|
+
|
|
21
|
+
"$comment_fonts": "Local @font-face families cannot ship to Framer. Substitute a family Framer serves; the script forces these with !important because the page's own :root rule is kept too and would otherwise silently win.",
|
|
22
|
+
"fontSubstitutions": {
|
|
23
|
+
"--font-display": "\"Fraunces\", ui-serif, Georgia, serif",
|
|
24
|
+
"--font-body": "\"IBM Plex Sans\", ui-sans-serif, system-ui, sans-serif"
|
|
25
|
+
},
|
|
26
|
+
"fontImport": "@import url(\"https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,400;9..144,500&family=IBM+Plex+Sans:wght@400;500;600&display=swap\");",
|
|
27
|
+
|
|
28
|
+
"textStyles": [
|
|
29
|
+
{ "name": "Display/Hero", "tag": "h1", "family": "Fraunces", "weight": 500, "size": 77, "lineHeight": "0.98em", "letterSpacing": "-0.01em" },
|
|
30
|
+
{ "name": "Body", "tag": "p", "family": "IBM Plex Sans", "weight": 400, "size": 17, "lineHeight": "1.6em" }
|
|
31
|
+
],
|
|
32
|
+
|
|
33
|
+
"$comment_breakpoints": "The base (widest) frame is created with the page. These are added on top. Place instances into the BASE only -- smaller breakpoints inherit.",
|
|
34
|
+
"breakpoints": [
|
|
35
|
+
{ "name": "Tablet", "width": 810, "viewportHeight": 1080 },
|
|
36
|
+
{ "name": "Phone", "width": 390, "viewportHeight": 844 }
|
|
37
|
+
],
|
|
38
|
+
|
|
39
|
+
"viewport": { "width": 1440, "height": 900 },
|
|
40
|
+
|
|
41
|
+
"$comment_tolerance": "Per-component height tolerance for framer-verify.mjs, default 0.04. Only ever widen one with a reason you have confirmed by screenshot -- a substituted font whose letterforms are a different width is the legitimate case.",
|
|
42
|
+
"verifyTolerance": { "MyTestimonial": 0.16 },
|
|
43
|
+
|
|
44
|
+
"pages": [
|
|
45
|
+
{
|
|
46
|
+
"file": "index.html",
|
|
47
|
+
"path": "/",
|
|
48
|
+
"$comment_sections": "Document order. `id` becomes the component's CSS wrapper class (.<id>-scope). `skipVerify` for components carrying real JS behaviour, which are checked by their own test instead.",
|
|
49
|
+
"sections": [
|
|
50
|
+
{ "id": "nav", "selector": "nav.nav", "component": "MyHeader", "title": "Site header", "skipVerify": false },
|
|
51
|
+
{ "id": "hero", "selector": ".hero-wrap","component": "MyHero", "title": "Hero", "skipVerify": true },
|
|
52
|
+
{ "id": "foot", "selector": ".footwrap", "component": "MyFooter", "title": "Site footer" }
|
|
53
|
+
],
|
|
54
|
+
"$comment_wire": "Names of wiring scripts this page's components need after extraction. Extraction only captures markup + CSS -- never JS -- so a component with real behaviour renders inert until its wiring script re-applies it.",
|
|
55
|
+
"wire": ["wire-header.mjs", "wire-hero.mjs"],
|
|
56
|
+
"$comment_place": "Placement order, defaults to `sections` order. Override when a page reuses components declared on another page.",
|
|
57
|
+
"place": ["MyHeader", "MyHero", "MyFooter"]
|
|
58
|
+
},
|
|
59
|
+
{
|
|
60
|
+
"file": "docs.html",
|
|
61
|
+
"path": "/docs",
|
|
62
|
+
"sections": [
|
|
63
|
+
{ "id": "docsbody", "selector": ".wrap", "component": "MyDocsBody", "title": "Docs body" }
|
|
64
|
+
],
|
|
65
|
+
"place": ["MyHeader", "MyDocsBody", "MyFooter"],
|
|
66
|
+
"$comment_controls": "Per-instance property-control values, applied when the instance is placed. Use for the one value that legitimately differs per page rather than duplicating a component.",
|
|
67
|
+
"controls": { "MyHeader": { "getStartedHref": "index.html#pricing" } }
|
|
68
|
+
}
|
|
69
|
+
]
|
|
70
|
+
}
|