@warpgogol/forge 0.13.0 → 0.15.0

package/skills/fo/ef-render-verify/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: ef-render-verify
+description: Verify an Editframe render — validate, build, check determinism, inspect output
+invocation: user
+category: fo
+concerns: read-only
+dependsOn: []
+languagePolicy: ref(PREFERENCES.md)
+---
+
+<!-- skill-lint-disable SKILL-17 -->
+
+# ef-render-verify
+
+Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
+
+A read-only verification of an Editframe render pipeline. The skill runs validation, build, determinism check, and output inspection, then reports pass/fail for each step. It does **not** modify any file.
+
+## Scope
+
+This skill verifies render output for `.tsx` composition files using the `editframe` stack profile. It uses `forge validate`, `forge build`, and `forge determinism check` — all profile-driven commands.
+
+## Process
+
+### 1. Pre-render validation
+
+Run `forge validate` to check the composition with the profile's validate command (typically `editframe check`). Review the output for any validation errors. If validation fails, report the errors and stop — do not proceed to render.
+
+### 2. Render
+
+Run `forge build` to produce the MP4 output. Review the output for any build errors. If the build fails, report the errors and stop.
+
+### 3. Determinism check
+
+Run `forge determinism check` to verify the render is reproducible — two builds produce identical output. Review the output hash comparison. If the hashes differ, report the mismatch and stop.
+
+### 4. Output inspection
+
+Check the render output:
+
+- Verify the output MP4 file exists at the expected path (`dist/{composition}.mp4`).
+- Check that the file size is non-zero.
+- Check that the duration matches the root `Timegroup`'s `duration` prop (if ffprobe or equivalent is available).
+
+### 5. Report
+
+Summarize the verification results — pass/fail for each step:
+
+| Step              | Status      | Details                                |
+| ----------------- | ----------- | -------------------------------------- |
+| Validation        | pass / fail | <error details or "all checks passed"> |
+| Build             | pass / fail | <error details or "build completed">   |
+| Determinism       | pass / fail | <hash comparison result>               |
+| Output inspection | pass / fail | <file exists, size, duration check>    |
+
+If all steps pass, the render is verified. If any step fails, provide specific recommendations for fixing the issue.

package/skills/fo/ef-webhooks/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: ef-webhooks
+description: "Configure Editframe webhooks for render completion and file processing notifications. Use when the operator asks to set up webhooks for Editframe events."
+invocation: user
+category: fo
+concerns: read-only
+dependsOn: []
+languagePolicy: ref(PREFERENCES.md)
+triggers:
+  - "set up editframe webhooks"
+  - "render completion notification"
+  - "file processing webhook"
+  - "webhook signature verification"
+source: https://editframe.com/skills/webhooks.md
+---
+
+<!-- skill-lint-disable SKILL-17 -->
+
+Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
+
+# Webhooks
+
+Use webhooks to receive real-time HTTP POST notifications when a render completes or a file finishes processing. Use them instead of polling `getRenderProgress`/`getFileProcessingProgress`.
+
+No SDK function registers a webhook. Configure one on an API key, through the dashboard (Settings → API Keys, or `editframe.com/resource/api_keys`). Set a **Webhook URL** (must use HTTPS). Select which **Webhook Events** (topics) to receive. When you create or update the key, the dashboard generates a **Webhook Secret**, used to sign deliveries. Copy this secret and store it alongside the API key.
+
+## Handling a webhook
+
+```typescript
+import express from "express";
+import crypto from "node:crypto";
+
+const app = express();
+
+app.post("/webhooks/editframe", express.raw({ type: "*/*" }), (req, res) => {
+  const signature = req.headers["x-webhook-signature"] as string;
+  const rawBody = req.body as Buffer;
+
+  const expected = crypto
+    .createHmac("sha256", process.env.EDITFRAME_WEBHOOK_SECRET!)
+    .update(rawBody)
+    .digest("hex");
+
+  if (!crypto.timingSafeEqual(Buffer.from(signature, "hex"), Buffer.from(expected, "hex"))) {
+    return res.status(401).send("Invalid signature");
+  }
+
+  res.status(200).send("OK");
+  const payload = JSON.parse(rawBody.toString("utf-8"));
+  processWebhookEvent(payload).catch(console.error);
+});
+```
+
+Every request carries an `X-Webhook-Signature` header: `HMAC-SHA256(webhook_secret, raw_json_body)`, hex-encoded. Verify with `crypto.timingSafeEqual`, not `===`.
+
+Use `express.raw()`, not `express.json()`. Signature verification needs the exact raw bytes. Re-serializing parsed JSON can reorder keys or change whitespace, which changes the hash and breaks verification.
+
+## Payload
+
+```typescript
+{ topic: string, data: {...} }
+```
+
+### Render topics
+
+`render.created`, `render.pending`, `render.rendering`, `render.completed`, `render.failed`
+
+`data` includes `id`, `status`, `created_at`, `completed_at`, `failed_at`, `width`, `height`, `fps`, `byte_size`, `duration_ms`, `md5`, `metadata`, `expires_at` (`null` = permanent), `download_url` (populated once complete), `error` (populated on failure).
+
+### File topics
+
+`file.created`, `file.uploading`, `file.processing`, `file.ready`, `file.failed`, `file.updated`
+
+`data` includes `id`, `type` (`video`/`image`/`caption`), `status`, `filename`, `byte_size`, `md5`, `mime_type`, `width`, `height`, `expires_at`. Editframe sends `file.updated` for a file status change that doesn't match one of the other file topics.
+
+### Legacy topics
+
+`image_file.created`, `isobmff_file.created`, `isobmff_track.created`, `unprocessed_file.created`. Do not build new integrations against these.
+
+## Delivery
+
+- Each event arrives as one HTTP POST with a JSON body.
+- Editframe retries on a fixed 10-second interval, up to 3 attempts total, with a 30-second timeout per attempt.
+- Editframe may deliver an event more than once. Key side effects off `data.id` to stay idempotent.
+- Always hash the **raw** request body for signature verification.
+
+## Testing
+
+```bash
+npx editframe webhook -t render.completed
+```
+
+This sends a real test event to the URL configured on your API key. There is no `--webhookURL` flag — the target URL always comes from the key's dashboard configuration. The dashboard's API key detail page has an equivalent "Test Webhook" button.
+
+For local development, tunnel your dev server (e.g. `ngrok http 3000`) and point the API key's Webhook URL at the tunnel URL.

package/skills/fo/fo-session-retro/SKILL.md

@@ -9,7 +9,7 @@ languagePolicy: ref(PREFERENCES.md)
 bindings:
   requires: []
   optional: [paths.invariantsFile]
-triggers: ["session retrospective", "capture insights from this session", "triage session discoveries", "Завершаем эту сессию", "Завершаем сессию", "Заканчиваем сессию", "Завершить сессию", "End session", "Wrap up", "Session end", "/session-end"]
+triggers: ["session retrospective", "capture insights from this session", "triage session discoveries", "Завершаем сессию", "/session-end"]
 ---
 
 # Session Retro
@@ -261,7 +261,7 @@ When gathering session insights, not every observation deserves to be saved. App
 
 **Do NOT save** — the observation is:
 
-- A one-off fact with no future impact (e.g. "RFC-0676 was skipped due to a duplicate"). These are historical events, not knowledge. They do not help future agents work better.
+- A one-off fact with no future impact (e.g. "an RFC was skipped due to a duplicate"). These are historical events, not knowledge. They do not help future agents work better.
 - A tool quirk already documented elsewhere (check `AGENTS.md` and existing memories first).
 - A transient state that will be irrelevant by the next session (e.g. "file X was dirty at session end").
 - A bug that was found and fixed in the same session with no broader lesson.

package/profiles/editframe-html-templates/composition-agents.md

@@ -1,34 +0,0 @@
-# Composition Workspace
-
-This workspace contains an Editframe video composition.
-
-## Domain terminology
-
-- **Composition** — the artifact this workspace produces (an HTML file using Editframe custom elements).
-- **Scene** — a structural module within a composition (an `ef-timegroup` block).
-- **Director** — the operator who creates and renders the composition.
-
-## Quality invariants
-
-- **VIDEO-01**: Composition filenames must use kebab-case (lowercase letters, digits, hyphens only). This ensures consistent naming across the project. Severity: error.
-- **VIDEO-02**: Scene durations must use `contain` fit mode by default to avoid unexpected cropping of video content. Use `cover` or `fill` only when intentionally overriding the default. Severity: warning.
-- **VIDEO-03**: All speech audio elements (`ef-audio` with speech content) must have corresponding `ef-captions` elements for accessibility. Severity: error.
-
-## Workflow
-
-1. Create a `.html` file with Editframe custom elements (`ef-timegroup`, `ef-video`, `ef-audio`, `ef-text`, `ef-captions`).
-2. Run `editframe preview` to preview the composition in the browser.
-3. Run `editframe check` to validate the composition structure.
-4. Run `editframe render -o dist/<name>.mp4` to produce the final video output.
-
-## Reference template
-
-A sample composition template is available at `editframe-html-templates/composition.html` in the forge profiles directory. Copy it to start a new composition:
-
-```sh
-cp node_modules/@warpgogol/forge/profiles/editframe-html-templates/composition.html compositions/my-new-video/composition.html
-```
-
-## File naming
-
-Composition files use kebab-case: `my-video.html`, `product-demo.html`, `intro-clip.html`.

package/profiles/editframe-html-templates/composition.html

@@ -1,32 +0,0 @@
-<!--
-  Editframe HTML composition template
-  Copy this file to start a new composition. Editframe custom elements:
-  - ef-timegroup: groups elements into a timed sequence
-  - ef-video: video source with fit mode (contain, cover, fill)
-  - ef-audio: audio source
-  - ef-text: text overlay with positioning
-  - ef-captions: accessibility captions for speech audio
-  Run `editframe preview` to preview, `editframe render` to produce output.
--->
-<ef-timegroup duration="10s">
-  <ef-video
-    src="assets/background.mp4"
-    fit="contain"
-    duration="10s"
-  ></ef-video>
-  <ef-text
-    text="Your text here"
-    x="50%"
-    y="50%"
-    font-size="48px"
-    color="white"
-    text-align="center"
-    duration="5s"
-  ></ef-text>
-  <ef-audio
-    src="assets/narration.mp3"
-  ></ef-audio>
-  <ef-captions
-    src="assets/captions.vtt"
-  ></ef-captions>
-</ef-timegroup>