@egbe-ai/opencode 0.0.0-stage → 0.1.8

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.
Files changed (479) hide show
  1. package/LICENSE +4 -0
  2. package/README.md +124 -2
  3. package/index.js +5 -0
  4. package/package.json +55 -4
  5. package/plugin.js +230 -0
  6. package/session-log.js +315 -0
  7. package/skills/.egbe-catalog/manifest.json +1 -0
  8. package/skills/egbe-os-analytics/SKILL.md +499 -0
  9. package/skills/egbe-os-analytics/canonical-events.v1.json +256 -0
  10. package/skills/egbe-os-analytics/references/session-funnel.md +130 -0
  11. package/skills/egbe-os-analytics/references/workflows/activation-tracking.md +147 -0
  12. package/skills/egbe-os-analytics/references/workflows/landing-click-tracking.md +209 -0
  13. package/skills/egbe-os-analytics/references/workflows/payment-lifecycle-tracking.md +122 -0
  14. package/skills/egbe-os-analytics/references/workflows/product-funnel-tracking.md +77 -0
  15. package/skills/egbe-os-analytics/references/workflows/signup-lifecycle-tracking.md +208 -0
  16. package/skills/egbe-os-analytics/scripts/umami_funnel.py +927 -0
  17. package/skills/egbe-os-apollo-lead-finder/SKILL.md +135 -0
  18. package/skills/egbe-os-apollo-lead-finder/references/operations.md +240 -0
  19. package/skills/egbe-os-apollo-lead-finder/scripts/enrich.js +6 -0
  20. package/skills/egbe-os-apollo-lead-finder/scripts/enrich.sh +4 -0
  21. package/skills/egbe-os-apollo-lead-finder/scripts/find-leads.js +6 -0
  22. package/skills/egbe-os-apollo-lead-finder/scripts/find-leads.sh +4 -0
  23. package/skills/egbe-os-apollo-lead-finder/scripts/lib/apollo-client.js +343 -0
  24. package/skills/egbe-os-apollo-lead-finder/scripts/lib/connection-identity.js +17 -0
  25. package/skills/egbe-os-apollo-lead-finder/scripts/lib/helpers.js +127 -0
  26. package/skills/egbe-os-apollo-lead-finder/scripts/lib/places-filters.js +217 -0
  27. package/skills/egbe-os-apollo-lead-finder/scripts/lib/sourcing.js +153 -0
  28. package/skills/egbe-os-apollo-lead-finder/scripts/places-leads.js +653 -0
  29. package/skills/egbe-os-apollo-lead-finder/scripts/places-leads.sh +4 -0
  30. package/skills/egbe-os-apollo-lead-finder/scripts/search.js +6 -0
  31. package/skills/egbe-os-apollo-lead-finder/scripts/search.sh +4 -0
  32. package/skills/egbe-os-campaign-landing-page/SKILL.md +95 -0
  33. package/skills/egbe-os-campaign-landing-page/agents/openai.yaml +4 -0
  34. package/skills/egbe-os-campaign-landing-page/references/leads-calendar-and-tracking.md +66 -0
  35. package/skills/egbe-os-campaign-landing-page/references/os-wiring.md +58 -0
  36. package/skills/egbe-os-campaign-landing-page/references/qa.md +40 -0
  37. package/skills/egbe-os-campaign-landing-page/references/routing.md +32 -0
  38. package/skills/egbe-os-db/SKILL.md +174 -0
  39. package/skills/egbe-os-deploy/SKILL.md +412 -0
  40. package/skills/egbe-os-design/SKILL.md +182 -0
  41. package/skills/egbe-os-design-landing-page/SKILL.md +117 -0
  42. package/skills/egbe-os-design-landing-page/agents/openai.yaml +4 -0
  43. package/skills/egbe-os-design-landing-page/assets/scaffold/.dockerignore +11 -0
  44. package/skills/egbe-os-design-landing-page/assets/scaffold/AGENTS.md +31 -0
  45. package/skills/egbe-os-design-landing-page/assets/scaffold/Dockerfile +21 -0
  46. package/skills/egbe-os-design-landing-page/assets/scaffold/eslint.config.mjs +18 -0
  47. package/skills/egbe-os-design-landing-page/assets/scaffold/next.config.ts +11 -0
  48. package/skills/egbe-os-design-landing-page/assets/scaffold/package.json +36 -0
  49. package/skills/egbe-os-design-landing-page/assets/scaffold/postcss.config.mjs +7 -0
  50. package/skills/egbe-os-design-landing-page/assets/scaffold/public/.gitkeep +1 -0
  51. package/skills/egbe-os-design-landing-page/assets/scaffold/sentry.edge.config.ts +13 -0
  52. package/skills/egbe-os-design-landing-page/assets/scaffold/sentry.server.config.ts +13 -0
  53. package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/global-error.tsx +19 -0
  54. package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/globals.css +22 -0
  55. package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/layout.tsx +21 -0
  56. package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/page.tsx +3 -0
  57. package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/privacy/page.tsx +28 -0
  58. package/skills/egbe-os-design-landing-page/assets/scaffold/src/components/egbe-analytics.tsx +39 -0
  59. package/skills/egbe-os-design-landing-page/assets/scaffold/src/instrumentation-client.ts +15 -0
  60. package/skills/egbe-os-design-landing-page/assets/scaffold/src/instrumentation.ts +13 -0
  61. package/skills/egbe-os-design-landing-page/assets/scaffold/src/lib/egbe-observability.generated.ts +20 -0
  62. package/skills/egbe-os-design-landing-page/assets/scaffold/src/lib/utils.ts +6 -0
  63. package/skills/egbe-os-design-landing-page/assets/scaffold/tsconfig.json +34 -0
  64. package/skills/egbe-os-design-landing-page/references/application-preparation.md +44 -0
  65. package/skills/egbe-os-design-landing-page/references/page-inputs.md +22 -0
  66. package/skills/egbe-os-destination-readiness/SKILL.md +132 -0
  67. package/skills/egbe-os-destination-readiness/references/checks.md +130 -0
  68. package/skills/egbe-os-destination-readiness/references/network-requirements.md +34 -0
  69. package/skills/egbe-os-destination-readiness/references/report.md +116 -0
  70. package/skills/egbe-os-domains/SKILL.md +189 -0
  71. package/skills/egbe-os-errors/SKILL.md +259 -0
  72. package/skills/egbe-os-git/SKILL.md +275 -0
  73. package/skills/egbe-os-git/references/issues.md +33 -0
  74. package/skills/egbe-os-google-ads/SKILL.md +163 -0
  75. package/skills/egbe-os-google-ads/references/artifacts.md +133 -0
  76. package/skills/egbe-os-google-ads/references/campaigns.md +157 -0
  77. package/skills/egbe-os-google-ads/references/conversions.md +153 -0
  78. package/skills/egbe-os-google-ads/references/delivery.md +128 -0
  79. package/skills/egbe-os-google-ads/references/keyword-ideas.md +40 -0
  80. package/skills/egbe-os-google-ads/references/reporting.md +105 -0
  81. package/skills/egbe-os-google-ads/references/search-assets.md +219 -0
  82. package/skills/egbe-os-google-ads/references/server-conversions.md +119 -0
  83. package/skills/egbe-os-google-auth/SKILL.md +285 -0
  84. package/skills/egbe-os-google-auth/agents/openai.yaml +4 -0
  85. package/skills/egbe-os-gtm-knowledge/SKILL.md +151 -0
  86. package/skills/egbe-os-images/SKILL.md +163 -0
  87. package/skills/egbe-os-images/references/stock-images.md +21 -0
  88. package/skills/egbe-os-instantly-campaign-launcher/SKILL.md +127 -0
  89. package/skills/egbe-os-instantly-campaign-launcher/references/instantly-ops.md +260 -0
  90. package/skills/egbe-os-instantly-campaign-launcher/references/observation-and-scheduling.md +188 -0
  91. package/skills/egbe-os-instantly-campaign-launcher/references/reply-handling.md +116 -0
  92. package/skills/egbe-os-instantly-campaign-launcher/references/run-spec-template.json +65 -0
  93. package/skills/egbe-os-instantly-campaign-launcher/references/run-state.md +145 -0
  94. package/skills/egbe-os-instantly-campaign-launcher/scripts/conclude-campaign.js +158 -0
  95. package/skills/egbe-os-instantly-campaign-launcher/scripts/install-crons.js +956 -0
  96. package/skills/egbe-os-instantly-campaign-launcher/scripts/launch-campaign.js +2008 -0
  97. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/campaign-metrics.js +124 -0
  98. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/confirmed-opt-outs.js +208 -0
  99. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/connection-identity.js +17 -0
  100. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/create-once.js +23 -0
  101. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/gtm-identity.js +125 -0
  102. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/helpers.js +545 -0
  103. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/html-body.js +266 -0
  104. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/instantly-client.js +328 -0
  105. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/outreach-db.js +370 -0
  106. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/recipient-exclusion/index.js +86 -0
  107. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/replenish-test-harness.js +53 -0
  108. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/reply-queue.js +67 -0
  109. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/run-config.js +103 -0
  110. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/sender-selection.js +105 -0
  111. package/skills/egbe-os-instantly-campaign-launcher/scripts/monitor-campaign.js +607 -0
  112. package/skills/egbe-os-instantly-campaign-launcher/scripts/outreach-report.js +147 -0
  113. package/skills/egbe-os-instantly-campaign-launcher/scripts/replenish-leads.js +619 -0
  114. package/skills/egbe-os-instantly-campaign-launcher/scripts/reply-worker.js +258 -0
  115. package/skills/egbe-os-instantly-campaign-launcher/scripts/run-cron-job.js +32 -0
  116. package/skills/egbe-os-instantly-campaign-launcher/scripts/send-reply.js +260 -0
  117. package/skills/egbe-os-linkedin-ads/SKILL.md +114 -0
  118. package/skills/egbe-os-linkedin-ads/references/destination-requirements.md +30 -0
  119. package/skills/egbe-os-linkedin-ads/references/runtime/api-reference.md +154 -0
  120. package/skills/egbe-os-linkedin-ads/references/runtime/artifacts.md +63 -0
  121. package/skills/egbe-os-linkedin-ads/references/workflows/build-paused.md +44 -0
  122. package/skills/egbe-os-linkedin-ads/references/workflows/conversions.md +88 -0
  123. package/skills/egbe-os-linkedin-ads/references/workflows/launch-and-pause.md +49 -0
  124. package/skills/egbe-os-linkedin-ads/references/workflows/monitoring.md +35 -0
  125. package/skills/egbe-os-linkedin-ads/references/workflows/readiness.md +63 -0
  126. package/skills/egbe-os-linkedin-ads/references/workflows/targeting-and-creative.md +52 -0
  127. package/skills/egbe-os-llm/SKILL.md +160 -0
  128. package/skills/egbe-os-mail/SKILL.md +180 -0
  129. package/skills/egbe-os-me/SKILL.md +119 -0
  130. package/skills/egbe-os-meta-ads/SKILL.md +114 -0
  131. package/skills/egbe-os-meta-ads/references/creative/creative-specs.md +15 -0
  132. package/skills/egbe-os-meta-ads/references/creative/talking-head.md +35 -0
  133. package/skills/egbe-os-meta-ads/references/destination-requirements.md +30 -0
  134. package/skills/egbe-os-meta-ads/references/runtime/api-reference.md +436 -0
  135. package/skills/egbe-os-meta-ads/references/runtime/artifacts.md +51 -0
  136. package/skills/egbe-os-meta-ads/references/runtime/insights-reference.md +187 -0
  137. package/skills/egbe-os-meta-ads/references/runtime/pixel-install.md +196 -0
  138. package/skills/egbe-os-meta-ads/references/runtime/shared-analytics-attribution.md +16 -0
  139. package/skills/egbe-os-meta-ads/references/workflows/build-paused.md +36 -0
  140. package/skills/egbe-os-meta-ads/references/workflows/launch-ready.md +16 -0
  141. package/skills/egbe-os-meta-ads/references/workflows/launch.md +23 -0
  142. package/skills/egbe-os-meta-ads/references/workflows/monitoring.md +72 -0
  143. package/skills/egbe-os-meta-ads/references/workflows/pause.md +17 -0
  144. package/skills/egbe-os-meta-ads/references/workflows/recovery.md +23 -0
  145. package/skills/egbe-os-meta-ads/scripts/check-pixel.py +229 -0
  146. package/skills/egbe-os-meta-ads/scripts/validate-meta-artifacts.py +187 -0
  147. package/skills/egbe-os-notifications/SKILL.md +78 -0
  148. package/skills/egbe-os-openai-ads/SKILL.md +149 -0
  149. package/skills/egbe-os-openai-ads/references/creative/chat-card.md +51 -0
  150. package/skills/egbe-os-openai-ads/references/destination-requirements.md +29 -0
  151. package/skills/egbe-os-openai-ads/references/runtime/api-reference.md +219 -0
  152. package/skills/egbe-os-openai-ads/references/runtime/artifacts.md +169 -0
  153. package/skills/egbe-os-openai-ads/references/workflows/build-paused.md +40 -0
  154. package/skills/egbe-os-openai-ads/references/workflows/conversions.md +40 -0
  155. package/skills/egbe-os-openai-ads/references/workflows/creative-assembly.md +24 -0
  156. package/skills/egbe-os-openai-ads/references/workflows/launch.md +27 -0
  157. package/skills/egbe-os-openai-ads/references/workflows/monitoring.md +54 -0
  158. package/skills/egbe-os-openai-ads/references/workflows/pause.md +22 -0
  159. package/skills/egbe-os-openai-ads/references/workflows/readiness.md +37 -0
  160. package/skills/egbe-os-openai-ads/references/workflows/tracking.md +32 -0
  161. package/skills/egbe-os-openai-ads/scripts/validate-openai-artifacts.py +271 -0
  162. package/skills/egbe-os-organic-trend-watch/SKILL.md +139 -0
  163. package/skills/egbe-os-organic-trend-watch/agents/openai.yaml +4 -0
  164. package/skills/egbe-os-organic-trend-watch/references/analysis-and-adaptation.md +54 -0
  165. package/skills/egbe-os-organic-trend-watch/references/collection-and-analysis.md +117 -0
  166. package/skills/egbe-os-organic-trend-watch/references/output-contract.md +133 -0
  167. package/skills/egbe-os-organic-trend-watch/references/provider-contract.md +169 -0
  168. package/skills/egbe-os-organic-trend-watch/references/runtime-contract.md +204 -0
  169. package/skills/egbe-os-organic-trend-watch/references/visual-analysis-prompt.md +17 -0
  170. package/skills/egbe-os-organic-trend-watch/scripts/_analysis.py +612 -0
  171. package/skills/egbe-os-organic-trend-watch/scripts/_contract.py +1133 -0
  172. package/skills/egbe-os-organic-trend-watch/scripts/_provider_inputs.py +165 -0
  173. package/skills/egbe-os-organic-trend-watch/scripts/analyze-visual-evidence.py +315 -0
  174. package/skills/egbe-os-organic-trend-watch/scripts/build-provider-inputs.py +88 -0
  175. package/skills/egbe-os-organic-trend-watch/scripts/connection_identity.py +22 -0
  176. package/skills/egbe-os-organic-trend-watch/scripts/egbe_artifacts.py +24 -0
  177. package/skills/egbe-os-organic-trend-watch/scripts/finalize-receipt.py +106 -0
  178. package/skills/egbe-os-organic-trend-watch/scripts/normalize-videos.py +647 -0
  179. package/skills/egbe-os-organic-trend-watch/scripts/prepare-visual-evidence.py +324 -0
  180. package/skills/egbe-os-organic-trend-watch/scripts/render-result.py +30 -0
  181. package/skills/egbe-os-organic-trend-watch/scripts/run-apify.py +723 -0
  182. package/skills/egbe-os-organic-trend-watch/scripts/run-state.py +192 -0
  183. package/skills/egbe-os-organic-trend-watch/scripts/validate-context.py +27 -0
  184. package/skills/egbe-os-organic-trend-watch/scripts/validate-runtime.py +137 -0
  185. package/skills/egbe-os-payments/SKILL.md +215 -0
  186. package/skills/egbe-os-payments/agents/openai.yaml +4 -0
  187. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/.egbe/scaffolds/billing-nextjs-subscription.v1.json +5 -0
  188. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/AGENTS.append.md +13 -0
  189. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/db/migrations/1000_egbe_billing.sql +66 -0
  190. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/package.fragment.json +12 -0
  191. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/scripts/billing-sync.mjs +162 -0
  192. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/account/billing/error.tsx +11 -0
  193. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/account/billing/loading.tsx +8 -0
  194. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/account/billing/page.tsx +121 -0
  195. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/api/billing/checkout/route.ts +102 -0
  196. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/api/billing/portal/route.ts +54 -0
  197. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/api/billing/status/route.ts +22 -0
  198. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/api/payments/webhook/route.ts +65 -0
  199. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/components/egbe-billing/plan-badge.tsx +16 -0
  200. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/billing-sync.test.mjs +58 -0
  201. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/catalog.ts +82 -0
  202. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/checkout-payload.ts +47 -0
  203. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/foundation-contract.test.mjs +59 -0
  204. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/lifecycle.d.ts +16 -0
  205. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/lifecycle.mjs +82 -0
  206. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/lifecycle.test.mjs +94 -0
  207. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/os-client.ts +96 -0
  208. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/plans.json +17 -0
  209. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/repository.ts +325 -0
  210. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/signature.d.ts +6 -0
  211. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/signature.mjs +22 -0
  212. package/skills/egbe-os-payments/references/contracts/plan-catalog.md +46 -0
  213. package/skills/egbe-os-payments/references/security/durable-verification.md +64 -0
  214. package/skills/egbe-os-payments/references/security/server-integration.md +26 -0
  215. package/skills/egbe-os-payments/references/security/webhook-and-entitlements.md +152 -0
  216. package/skills/egbe-os-payments/references/ux/billing-experience.md +47 -0
  217. package/skills/egbe-os-payments/references/workflows/account-billing.md +64 -0
  218. package/skills/egbe-os-payments/references/workflows/discounts-and-promotion-codes.md +265 -0
  219. package/skills/egbe-os-payments/references/workflows/one-time-purchase.md +75 -0
  220. package/skills/egbe-os-payments/references/workflows/product-checkout.md +355 -0
  221. package/skills/egbe-os-payments/references/workflows/subscription-lifecycle.md +55 -0
  222. package/skills/egbe-os-playbook/SKILL.md +79 -0
  223. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/email-outreach.md +91 -0
  224. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/google-search.md +40 -0
  225. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/linkedin.md +24 -0
  226. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/meta.md +23 -0
  227. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/openai.md +15 -0
  228. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/reddit.md +56 -0
  229. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/choose-test.md +73 -0
  230. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/evaluate.md +91 -0
  231. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/market.md +96 -0
  232. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/run-test.md +111 -0
  233. package/skills/egbe-os-playbook/playbooks/market-and-acquisition.md +56 -0
  234. package/skills/egbe-os-playbook/playbooks/product/business-loop.md +141 -0
  235. package/skills/egbe-os-playbook/playbooks/product/collaboration.md +26 -0
  236. package/skills/egbe-os-playbook/playbooks/product/deliver.md +75 -0
  237. package/skills/egbe-os-playbook/playbooks/product/diagnose.md +80 -0
  238. package/skills/egbe-os-playbook/playbooks/product/evaluate.md +67 -0
  239. package/skills/egbe-os-playbook/playbooks/product/experience.md +132 -0
  240. package/skills/egbe-os-playbook/playbooks/product/loop-examples.md +67 -0
  241. package/skills/egbe-os-playbook/playbooks/product/offer.md +65 -0
  242. package/skills/egbe-os-playbook/playbooks/product/value.md +91 -0
  243. package/skills/egbe-os-playbook/playbooks/product.md +67 -0
  244. package/skills/egbe-os-playbook/references/catalog.md +127 -0
  245. package/skills/egbe-os-playbook/references/changes.md +167 -0
  246. package/skills/egbe-os-playbook/scripts/playbook-changes.py +6 -0
  247. package/skills/egbe-os-playbook/scripts/playbook_changes/__init__.py +1 -0
  248. package/skills/egbe-os-playbook/scripts/playbook_changes/cli.py +57 -0
  249. package/skills/egbe-os-playbook/scripts/playbook_changes/operations.py +137 -0
  250. package/skills/egbe-os-playbook/scripts/playbook_changes/protocol.py +132 -0
  251. package/skills/egbe-os-playbook/scripts/playbook_changes/storage.py +180 -0
  252. package/skills/egbe-os-playbook/scripts/playbook_changes/transport.py +113 -0
  253. package/skills/egbe-os-product-auth/SKILL.md +151 -0
  254. package/skills/egbe-os-product-auth/agents/openai.yaml +4 -0
  255. package/skills/egbe-os-product-auth/assets/db/README.md +102 -0
  256. package/skills/egbe-os-product-auth/assets/db/create-validation-session.mjs +223 -0
  257. package/skills/egbe-os-product-auth/assets/db/migrate.mjs +64 -0
  258. package/skills/egbe-os-product-auth/assets/db/migrations/0001_auth.sql +33 -0
  259. package/skills/egbe-os-product-auth/assets/db/migrations/0002_auth_identities.sql +16 -0
  260. package/skills/egbe-os-product-auth/assets/scaffolds/product-auth-database/AGENTS.append.md +17 -0
  261. package/skills/egbe-os-product-auth/assets/scaffolds/product-auth-database/package.fragment.json +10 -0
  262. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/AGENTS.append.md +9 -0
  263. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/package.fragment.json +13 -0
  264. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/src/lib/egbe-product/db.ts +31 -0
  265. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/src/lib/egbe-product/identity.ts +94 -0
  266. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/src/lib/egbe-product/index.ts +3 -0
  267. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/src/lib/egbe-product/session.ts +91 -0
  268. package/skills/egbe-os-product-auth/references/contracts/live-auth-interface.md +108 -0
  269. package/skills/egbe-os-product-auth/references/frameworks/nextjs.md +34 -0
  270. package/skills/egbe-os-product-auth/references/security/session-and-credentials.md +73 -0
  271. package/skills/egbe-os-product-auth/references/ux/auth-experience.md +58 -0
  272. package/skills/egbe-os-product-auth/references/workflows/account-recovery.md +22 -0
  273. package/skills/egbe-os-product-auth/references/workflows/build-auth.md +212 -0
  274. package/skills/egbe-os-product-auth/references/workflows/google.md +34 -0
  275. package/skills/egbe-os-product-auth/references/workflows/passwordless-email.md +65 -0
  276. package/skills/egbe-os-product-build/SKILL.md +111 -0
  277. package/skills/egbe-os-product-build/agents/openai.yaml +4 -0
  278. package/skills/egbe-os-product-build/references/capabilities.md +25 -0
  279. package/skills/egbe-os-product-build/references/engineering.md +72 -0
  280. package/skills/egbe-os-product-build/references/execution.md +55 -0
  281. package/skills/egbe-os-product-build/references/foundations.md +93 -0
  282. package/skills/egbe-os-product-build/references/interface-quality.md +32 -0
  283. package/skills/egbe-os-product-build/references/workflows/private-review-handoff.md +86 -0
  284. package/skills/egbe-os-product-build/scripts/scaffold.py +296 -0
  285. package/skills/egbe-os-product-demo-video/SKILL.md +118 -0
  286. package/skills/egbe-os-product-demo-video/references/recording.md +32 -0
  287. package/skills/egbe-os-product-market-research/SKILL.md +159 -0
  288. package/skills/egbe-os-product-market-research/agents/openai.yaml +4 -0
  289. package/skills/egbe-os-product-market-research/references/catalog.v1.json +177 -0
  290. package/skills/egbe-os-product-market-research/references/config/channel-footprint-sources.v1.json +99 -0
  291. package/skills/egbe-os-product-market-research/references/config/creative-taxonomy.v1.json +367 -0
  292. package/skills/egbe-os-product-market-research/references/contracts/creative-video.md +75 -0
  293. package/skills/egbe-os-product-market-research/references/contracts/funnel-teardown.md +235 -0
  294. package/skills/egbe-os-product-market-research/references/contracts/geography-comparison.md +71 -0
  295. package/skills/egbe-os-product-market-research/references/contracts/lifecycle-capture.md +119 -0
  296. package/skills/egbe-os-product-market-research/references/contracts/research-artifacts.md +520 -0
  297. package/skills/egbe-os-product-market-research/references/contracts/walk-mechanics.v2.json +18 -0
  298. package/skills/egbe-os-product-market-research/references/prompts/acquisition-channels.md +137 -0
  299. package/skills/egbe-os-product-market-research/references/prompts/acquisition-channels.user.md +4 -0
  300. package/skills/egbe-os-product-market-research/references/prompts/competitive-landscape.md +118 -0
  301. package/skills/egbe-os-product-market-research/references/prompts/competitive-landscape.user.md +4 -0
  302. package/skills/egbe-os-product-market-research/references/prompts/demand-validation.md +154 -0
  303. package/skills/egbe-os-product-market-research/references/prompts/demand-validation.user.md +4 -0
  304. package/skills/egbe-os-product-market-research/references/prompts/market-size-and-dynamics.md +100 -0
  305. package/skills/egbe-os-product-market-research/references/prompts/market-size-and-dynamics.user.md +4 -0
  306. package/skills/egbe-os-product-market-research/references/prompts/pricing-and-monetization.md +126 -0
  307. package/skills/egbe-os-product-market-research/references/prompts/pricing-and-monetization.user.md +4 -0
  308. package/skills/egbe-os-product-market-research/references/prompts/target-audience.md +98 -0
  309. package/skills/egbe-os-product-market-research/references/prompts/target-audience.user.md +4 -0
  310. package/skills/egbe-os-product-market-research/references/prompts/unit-economics.md +217 -0
  311. package/skills/egbe-os-product-market-research/references/prompts/unit-economics.user.md +4 -0
  312. package/skills/egbe-os-product-market-research/references/prompts/value-proposition.md +113 -0
  313. package/skills/egbe-os-product-market-research/references/prompts/value-proposition.user.md +4 -0
  314. package/skills/egbe-os-product-market-research/references/workflows/acquisition-channels.md +27 -0
  315. package/skills/egbe-os-product-market-research/references/workflows/channel-footprint.md +163 -0
  316. package/skills/egbe-os-product-market-research/references/workflows/community-demand.md +100 -0
  317. package/skills/egbe-os-product-market-research/references/workflows/competitive-landscape.md +27 -0
  318. package/skills/egbe-os-product-market-research/references/workflows/competitor-ads.md +82 -0
  319. package/skills/egbe-os-product-market-research/references/workflows/competitor-set.md +300 -0
  320. package/skills/egbe-os-product-market-research/references/workflows/creative-patterns.md +228 -0
  321. package/skills/egbe-os-product-market-research/references/workflows/demand-validation.md +27 -0
  322. package/skills/egbe-os-product-market-research/references/workflows/fleet-prior.md +80 -0
  323. package/skills/egbe-os-product-market-research/references/workflows/funnel-teardown.md +184 -0
  324. package/skills/egbe-os-product-market-research/references/workflows/geography-comparison.md +84 -0
  325. package/skills/egbe-os-product-market-research/references/workflows/keyword-economics.md +122 -0
  326. package/skills/egbe-os-product-market-research/references/workflows/lifecycle-capture.md +218 -0
  327. package/skills/egbe-os-product-market-research/references/workflows/local-research.md +55 -0
  328. package/skills/egbe-os-product-market-research/references/workflows/market-size-and-dynamics.md +27 -0
  329. package/skills/egbe-os-product-market-research/references/workflows/preview.md +175 -0
  330. package/skills/egbe-os-product-market-research/references/workflows/pricing-and-monetization.md +27 -0
  331. package/skills/egbe-os-product-market-research/references/workflows/recommendations.md +35 -0
  332. package/skills/egbe-os-product-market-research/references/workflows/review-mining.md +76 -0
  333. package/skills/egbe-os-product-market-research/references/workflows/target-audience.md +27 -0
  334. package/skills/egbe-os-product-market-research/references/workflows/tiktok-reels-market-trends.md +46 -0
  335. package/skills/egbe-os-product-market-research/references/workflows/unit-economics.md +27 -0
  336. package/skills/egbe-os-product-market-research/references/workflows/value-proposition.md +27 -0
  337. package/skills/egbe-os-product-market-research/scripts/build-organic-trend-context.py +167 -0
  338. package/skills/egbe-os-product-market-research/scripts/build-preview-context.py +91 -0
  339. package/skills/egbe-os-product-market-research/scripts/build-research-query.py +225 -0
  340. package/skills/egbe-os-product-market-research/scripts/channel-footprint-model.py +294 -0
  341. package/skills/egbe-os-product-market-research/scripts/connection_identity.py +22 -0
  342. package/skills/egbe-os-product-market-research/scripts/creative-model.py +364 -0
  343. package/skills/egbe-os-product-market-research/scripts/creative-selection.py +113 -0
  344. package/skills/egbe-os-product-market-research/scripts/creative-semantics.py +365 -0
  345. package/skills/egbe-os-product-market-research/scripts/creative-video.py +542 -0
  346. package/skills/egbe-os-product-market-research/scripts/egbe_artifacts.py +24 -0
  347. package/skills/egbe-os-product-market-research/scripts/finalize-organic-trend-watch.py +304 -0
  348. package/skills/egbe-os-product-market-research/scripts/funnel-email-review.py +97 -0
  349. package/skills/egbe-os-product-market-research/scripts/funnel-model.py +966 -0
  350. package/skills/egbe-os-product-market-research/scripts/funnel_features.py +50 -0
  351. package/skills/egbe-os-product-market-research/scripts/geography-comparison-contract.py +172 -0
  352. package/skills/egbe-os-product-market-research/scripts/geography-comparison.py +169 -0
  353. package/skills/egbe-os-product-market-research/scripts/keyword-forecast.py +61 -0
  354. package/skills/egbe-os-product-market-research/scripts/keyword-locale-publication.py +136 -0
  355. package/skills/egbe-os-product-market-research/scripts/lifecycle-start.py +190 -0
  356. package/skills/egbe-os-product-market-research/scripts/persist-research-report.py +63 -0
  357. package/skills/egbe-os-product-market-research/scripts/research-artifact-io.py +281 -0
  358. package/skills/egbe-os-product-market-research/scripts/research-evidence.py +496 -0
  359. package/skills/egbe-os-product-market-research/scripts/research-policy.py +33 -0
  360. package/skills/egbe-os-product-market-research/scripts/research-section-runtime.py +343 -0
  361. package/skills/egbe-os-product-market-research/scripts/research-section-workflow.py +288 -0
  362. package/skills/egbe-os-product-market-research/scripts/research_integrity.py +122 -0
  363. package/skills/egbe-os-product-market-research/scripts/review-research-completion.py +306 -0
  364. package/skills/egbe-os-product-market-research/scripts/run-acquisition-channels.py +72 -0
  365. package/skills/egbe-os-product-market-research/scripts/run-channel-footprint.py +2258 -0
  366. package/skills/egbe-os-product-market-research/scripts/run-community-demand.py +1603 -0
  367. package/skills/egbe-os-product-market-research/scripts/run-competitive-landscape.py +66 -0
  368. package/skills/egbe-os-product-market-research/scripts/run-competitor-ads.py +1156 -0
  369. package/skills/egbe-os-product-market-research/scripts/run-competitor-set.py +2514 -0
  370. package/skills/egbe-os-product-market-research/scripts/run-creative-patterns.py +2042 -0
  371. package/skills/egbe-os-product-market-research/scripts/run-demand-validation.py +72 -0
  372. package/skills/egbe-os-product-market-research/scripts/run-fleet-prior.py +652 -0
  373. package/skills/egbe-os-product-market-research/scripts/run-funnel-teardown.py +493 -0
  374. package/skills/egbe-os-product-market-research/scripts/run-keyword-economics.py +1443 -0
  375. package/skills/egbe-os-product-market-research/scripts/run-lifecycle-capture.py +1543 -0
  376. package/skills/egbe-os-product-market-research/scripts/run-market-size-and-dynamics.py +66 -0
  377. package/skills/egbe-os-product-market-research/scripts/run-os-research.py +311 -0
  378. package/skills/egbe-os-product-market-research/scripts/run-pricing-and-monetization.py +71 -0
  379. package/skills/egbe-os-product-market-research/scripts/run-review-mining.py +1051 -0
  380. package/skills/egbe-os-product-market-research/scripts/run-target-audience.py +66 -0
  381. package/skills/egbe-os-product-market-research/scripts/run-unit-economics.py +71 -0
  382. package/skills/egbe-os-product-market-research/scripts/run-value-proposition.py +67 -0
  383. package/skills/egbe-os-product-market-research/scripts/upsert-markdown-section.py +156 -0
  384. package/skills/egbe-os-product-market-research/scripts/walk-funnels.py +249 -0
  385. package/skills/egbe-os-product-market-research/scripts/write-preview.py +710 -0
  386. package/skills/egbe-os-product-market-research/scripts/write-recommendations.py +272 -0
  387. package/skills/egbe-os-product-report/SKILL.md +150 -0
  388. package/skills/egbe-os-product-report/references/artifacts.md +84 -0
  389. package/skills/egbe-os-product-report/references/brief.md +34 -0
  390. package/skills/egbe-os-product-report/references/daily.md +76 -0
  391. package/skills/egbe-os-product-report/references/sources.md +68 -0
  392. package/skills/egbe-os-product-routines/SKILL.md +166 -0
  393. package/skills/egbe-os-product-routines/references/catalog.md +22 -0
  394. package/skills/egbe-os-product-routines/references/continuation-check.md +41 -0
  395. package/skills/egbe-os-product-routines/references/product-reporting.md +163 -0
  396. package/skills/egbe-os-product-routines/references/run-preset.md +32 -0
  397. package/skills/egbe-os-quickstart/scripts/egbe-curl.py +357 -0
  398. package/skills/egbe-os-quiz-funnel/SKILL.md +152 -0
  399. package/skills/egbe-os-quiz-funnel/agents/openai.yaml +4 -0
  400. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-engine.d.mts +224 -0
  401. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-engine.mjs +652 -0
  402. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-engine.test.mjs +764 -0
  403. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-history.d.mts +31 -0
  404. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-history.mjs +87 -0
  405. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-history.test.mjs +265 -0
  406. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-reference.test.mjs +254 -0
  407. package/skills/egbe-os-quiz-funnel/assets/examples/egbe-docs/product/quizzes/books-checkup/QUIZ.md +195 -0
  408. package/skills/egbe-os-quiz-funnel/assets/examples/egbe-docs/product/quizzes/books-checkup/quiz.json +421 -0
  409. package/skills/egbe-os-quiz-funnel/assets/examples/egbe-docs/product/quizzes/books-checkup/quiz.public.json +369 -0
  410. package/skills/egbe-os-quiz-funnel/assets/examples/egbe-docs/product/quizzes/books-checkup/validation.json +21 -0
  411. package/skills/egbe-os-quiz-funnel/assets/reference/index.html +26 -0
  412. package/skills/egbe-os-quiz-funnel/assets/reference/quiz-bootstrap.js +31 -0
  413. package/skills/egbe-os-quiz-funnel/assets/reference/quiz-early-actions.mjs +11 -0
  414. package/skills/egbe-os-quiz-funnel/assets/reference/quiz-first-screen.mjs +32 -0
  415. package/skills/egbe-os-quiz-funnel/assets/reference/quiz-page.mjs +480 -0
  416. package/skills/egbe-os-quiz-funnel/assets/reference/quiz.css +264 -0
  417. package/skills/egbe-os-quiz-funnel/references/competitor-teardown.md +159 -0
  418. package/skills/egbe-os-quiz-funnel/references/conversion-handoff.md +156 -0
  419. package/skills/egbe-os-quiz-funnel/references/implementation.md +207 -0
  420. package/skills/egbe-os-quiz-funnel/references/inputs.md +37 -0
  421. package/skills/egbe-os-quiz-funnel/references/measurement.md +122 -0
  422. package/skills/egbe-os-quiz-funnel/references/spec-contract.md +335 -0
  423. package/skills/egbe-os-quiz-funnel/references/verification.md +101 -0
  424. package/skills/egbe-os-quiz-funnel/references/walk-mechanics.v2.json +18 -0
  425. package/skills/egbe-os-quiz-funnel/scripts/compile-quiz-spec.py +1869 -0
  426. package/skills/egbe-os-quiz-funnel/scripts/prepare-research-identity.py +66 -0
  427. package/skills/egbe-os-reddit-ads/SKILL.md +121 -0
  428. package/skills/egbe-os-reddit-ads/assets/static-banners/bold-statement/schema.json +41 -0
  429. package/skills/egbe-os-reddit-ads/assets/static-banners/bold-statement/template.html +106 -0
  430. package/skills/egbe-os-reddit-ads/assets/static-banners/data-proof/schema.json +61 -0
  431. package/skills/egbe-os-reddit-ads/assets/static-banners/data-proof/template.html +151 -0
  432. package/skills/egbe-os-reddit-ads/assets/static-banners/honest-breakdown/schema.json +91 -0
  433. package/skills/egbe-os-reddit-ads/assets/static-banners/honest-breakdown/template.html +185 -0
  434. package/skills/egbe-os-reddit-ads/assets/static-banners/question-hook/schema.json +51 -0
  435. package/skills/egbe-os-reddit-ads/assets/static-banners/question-hook/template.html +121 -0
  436. package/skills/egbe-os-reddit-ads/assets/static-banners/reddit-post-style/schema.json +87 -0
  437. package/skills/egbe-os-reddit-ads/assets/static-banners/reddit-post-style/template.html +212 -0
  438. package/skills/egbe-os-reddit-ads/references/creative/html-to-png-pipeline.md +123 -0
  439. package/skills/egbe-os-reddit-ads/references/creative/static-banner-qa.md +12 -0
  440. package/skills/egbe-os-reddit-ads/references/creative/static-banner-system.md +16 -0
  441. package/skills/egbe-os-reddit-ads/references/destination-requirements.md +36 -0
  442. package/skills/egbe-os-reddit-ads/references/runtime/api-reference.md +435 -0
  443. package/skills/egbe-os-reddit-ads/references/runtime/artifacts.md +57 -0
  444. package/skills/egbe-os-reddit-ads/references/runtime/monitoring.md +64 -0
  445. package/skills/egbe-os-reddit-ads/references/runtime/pixel-and-tracking.md +49 -0
  446. package/skills/egbe-os-reddit-ads/references/runtime/policies.md +19 -0
  447. package/skills/egbe-os-reddit-ads/references/runtime/shared-analytics-attribution.md +14 -0
  448. package/skills/egbe-os-reddit-ads/references/workflows/build-paused.md +35 -0
  449. package/skills/egbe-os-reddit-ads/references/workflows/launch-ready.md +19 -0
  450. package/skills/egbe-os-reddit-ads/references/workflows/launch.md +32 -0
  451. package/skills/egbe-os-reddit-ads/references/workflows/readiness.md +9 -0
  452. package/skills/egbe-os-reddit-ads/scripts/capture-ad.sh +178 -0
  453. package/skills/egbe-os-reddit-ads/scripts/validate-reddit-artifacts.py +187 -0
  454. package/skills/egbe-os-report-ui/SKILL.md +133 -0
  455. package/skills/egbe-os-report-ui/assets/egbe-wordmark.svg +9 -0
  456. package/skills/egbe-os-report-ui/assets/examples/components.html +417 -0
  457. package/skills/egbe-os-report-ui/assets/examples/editorial.html +209 -0
  458. package/skills/egbe-os-report-ui/assets/scaffold.html +179 -0
  459. package/skills/egbe-os-report-ui/references/components.md +209 -0
  460. package/skills/egbe-os-research/SKILL.md +125 -0
  461. package/skills/egbe-os-saas-unit-economics/SKILL.md +188 -0
  462. package/skills/egbe-os-scrape/SKILL.md +160 -0
  463. package/skills/egbe-os-search/SKILL.md +182 -0
  464. package/skills/egbe-os-search/references/google-places.md +81 -0
  465. package/skills/egbe-os-support/SKILL.md +149 -0
  466. package/skills/egbe-os-telemetry/SKILL.md +344 -0
  467. package/skills/egbe-os-telemetry/references/harnesses/claude-code.md +97 -0
  468. package/skills/egbe-os-telemetry/references/harnesses/codex.md +22 -0
  469. package/skills/egbe-os-telemetry/references/harnesses/hermes.md +39 -0
  470. package/skills/egbe-os-telemetry/references/harnesses/openclaw.md +139 -0
  471. package/skills/egbe-os-telemetry/references/harnesses/opencode.md +28 -0
  472. package/skills/egbe-os-tools/SKILL.md +180 -0
  473. package/skills/egbe-os-tools/references/theona.md +26 -0
  474. package/skills/egbe-os-wallet/SKILL.md +181 -0
  475. package/skills/egbe-setup/EGBE.md +484 -0
  476. package/skills/egbe-setup/SKILL.md +116 -0
  477. package/skills/egbe-setup/references/project.md +80 -0
  478. package/state.js +37 -0
  479. package/update.js +361 -0
@@ -0,0 +1,647 @@
1
+ #!/usr/bin/env python3
2
+ """Normalize source observations without deciding their cause or business value."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import argparse
7
+ import hashlib
8
+ import json
9
+ import math
10
+ import statistics
11
+ import sys
12
+ import urllib.parse
13
+ from datetime import datetime, timezone
14
+ from pathlib import Path
15
+ from typing import Any
16
+
17
+ from _contract import (
18
+ ANALYSIS_CONTRACT_VERSION,
19
+ ContractError,
20
+ SCHEMA_VERSION,
21
+ TIKTOK_COMMENTS_BUNDLE_PATH,
22
+ atomic_write_json,
23
+ extract_rows,
24
+ load_run_state,
25
+ parse_rfc3339,
26
+ read_json,
27
+ resolve_relative,
28
+ sha256_file,
29
+ validate_linked_tiktok_comments_bundle,
30
+ validate_raw_manifest,
31
+ validate_context,
32
+ )
33
+ from _provider_inputs import validate_collection_window
34
+
35
+
36
+ AD_MARKERS = ("#ad", "#sponsored", "#partnership", "paid partnership", "thanks @")
37
+
38
+
39
+ def _nested(value: dict[str, Any], path: str) -> Any:
40
+ current: Any = value
41
+ for part in path.split("."):
42
+ if not isinstance(current, dict) or part not in current:
43
+ return None
44
+ current = current[part]
45
+ return current
46
+
47
+
48
+ def _first(value: dict[str, Any], *paths: str) -> Any:
49
+ for path in paths:
50
+ candidate = _nested(value, path)
51
+ if candidate is not None:
52
+ return candidate
53
+ return None
54
+
55
+
56
+ def _text(value: Any) -> str | None:
57
+ if isinstance(value, str) and value.strip():
58
+ return value.strip()
59
+ if isinstance(value, (int, float)) and not isinstance(value, bool):
60
+ return str(value)
61
+ return None
62
+
63
+
64
+ def _number(value: Any) -> float | int | None:
65
+ if value is None or isinstance(value, bool):
66
+ return None
67
+ try:
68
+ result = float(value)
69
+ except (TypeError, ValueError):
70
+ return None
71
+ if not math.isfinite(result) or result < 0:
72
+ return None
73
+ return int(result) if result.is_integer() else result
74
+
75
+
76
+ def _handle(value: Any) -> str | None:
77
+ text = _text(value)
78
+ if text is None:
79
+ return None
80
+ return text.lstrip("@").strip().casefold() or None
81
+
82
+
83
+ def _timestamp(value: Any) -> datetime | None:
84
+ if isinstance(value, (int, float)) and not isinstance(value, bool):
85
+ try:
86
+ result = datetime.fromtimestamp(float(value), tz=timezone.utc)
87
+ except (OverflowError, OSError, ValueError):
88
+ return None
89
+ return result
90
+ text = _text(value)
91
+ if text is None:
92
+ return None
93
+ if text.isdigit():
94
+ return _timestamp(int(text))
95
+ normalized = text[:-1] + "+00:00" if text.endswith("Z") else text
96
+ try:
97
+ result = datetime.fromisoformat(normalized)
98
+ except ValueError:
99
+ return None
100
+ if result.tzinfo is None:
101
+ result = result.replace(tzinfo=timezone.utc)
102
+ return result.astimezone(timezone.utc)
103
+
104
+
105
+ def _safe_ratio(numerator: float | int | None, denominator: float | int | None) -> float | None:
106
+ if numerator is None or denominator is None or denominator <= 0:
107
+ return None
108
+ return float(numerator) / float(denominator)
109
+
110
+
111
+ def _canonical_url(platform: str, row: dict[str, Any], video_id: str, handle: str) -> str:
112
+ candidates = (
113
+ _text(_first(row, "webVideoUrl")),
114
+ _text(_first(row, "postUrl")),
115
+ _text(_first(row, "inputUrl")),
116
+ _text(_first(row, "url")),
117
+ )
118
+ for explicit in candidates:
119
+ if not explicit or not explicit.startswith(("https://", "http://")):
120
+ continue
121
+ host = (urllib.parse.urlparse(explicit).hostname or "").casefold()
122
+ if platform == "tiktok" and (host == "tiktok.com" or host.endswith(".tiktok.com")):
123
+ return explicit
124
+ if platform == "instagram" and (
125
+ host == "instagram.com" or host.endswith(".instagram.com")
126
+ ):
127
+ return explicit
128
+ if platform == "tiktok":
129
+ return f"https://www.tiktok.com/@{handle}/video/{video_id}"
130
+ short_code = _text(_first(row, "shortCode", "shortcode", "code")) or video_id
131
+ return f"https://www.instagram.com/reel/{short_code}/"
132
+
133
+
134
+ def _comments(row: dict[str, Any]) -> list[dict[str, Any]]:
135
+ raw = _first(row, "comments", "latestComments", "topComments")
136
+ if not isinstance(raw, list):
137
+ return []
138
+ result: list[dict[str, Any]] = []
139
+ seen: set[str] = set()
140
+ for item in raw:
141
+ if isinstance(item, str):
142
+ text, likes, provider_id = item.strip(), None, None
143
+ elif isinstance(item, dict):
144
+ text = _text(_first(item, "text", "comment", "content")) or ""
145
+ likes = _number(_first(item, "diggCount", "likesCount", "likes", "likeCount"))
146
+ provider_id = _text(
147
+ _first(item, "cid", "id", "commentId", "comment_id")
148
+ )
149
+ else:
150
+ continue
151
+ if not text or text in seen:
152
+ continue
153
+ seen.add(text)
154
+ comment_id = (
155
+ f"provider:{provider_id}"
156
+ if provider_id
157
+ else f"text-sha256:{hashlib.sha256(text.encode('utf-8')).hexdigest()}"
158
+ )
159
+ result.append({"comment_id": comment_id, "text": text, "likes": likes})
160
+ result.sort(key=lambda item: (item["likes"] is None, -(item["likes"] or 0), item["text"]))
161
+ return result[:20]
162
+
163
+
164
+ def _merge_comments(
165
+ left: list[dict[str, Any]],
166
+ right: list[dict[str, Any]],
167
+ ) -> list[dict[str, Any]]:
168
+ merged = {item["text"]: item for item in left}
169
+ for item in right:
170
+ merged[item["text"]] = item
171
+ return sorted(
172
+ merged.values(),
173
+ key=lambda item: (item["likes"] is None, -(item["likes"] or 0), item["text"]),
174
+ )[:20]
175
+
176
+
177
+ def _hashtags(row: dict[str, Any], caption: str) -> list[str]:
178
+ values = _first(row, "hashtags", "hashTags")
179
+ result: list[str] = []
180
+ if isinstance(values, list):
181
+ for item in values:
182
+ if isinstance(item, dict):
183
+ item = _first(item, "name", "title")
184
+ text = _text(item)
185
+ if text:
186
+ result.append(text.lstrip("#").casefold())
187
+ for token in caption.split():
188
+ if token.startswith("#") and len(token) > 1:
189
+ result.append(token[1:].strip(".,!?;:()[]{}").casefold())
190
+ return sorted(set(result))
191
+
192
+
193
+ def _normalize_row(
194
+ *,
195
+ platform: str,
196
+ row: dict[str, Any],
197
+ accounts: dict[tuple[str, str], dict[str, Any]],
198
+ collected_at: datetime,
199
+ ) -> dict[str, Any] | None:
200
+ video_id = _text(_first(row, "id", "videoId", "aweme_id", "shortCode", "code"))
201
+ handle = _handle(
202
+ _first(
203
+ row,
204
+ "authorMeta.name",
205
+ "authorMeta.uniqueId",
206
+ "author.uniqueId",
207
+ "ownerUsername",
208
+ "owner.username",
209
+ "username",
210
+ "profileName",
211
+ )
212
+ )
213
+ if not video_id or not handle:
214
+ raise ContractError("provider observation is missing its video ID or account handle")
215
+ account = accounts.get((platform, handle))
216
+ if account is None:
217
+ return None
218
+
219
+ posted = _timestamp(_first(row, "createTime", "timestamp", "takenAt", "publishedAt"))
220
+ age_days: int | None = None
221
+ if posted is not None:
222
+ age_days = max(0, (collected_at.date() - posted.date()).days)
223
+ caption = _text(_first(row, "text", "caption", "description")) or ""
224
+ hashtags = _hashtags(row, caption)
225
+
226
+ views = _number(_first(row, "playCount", "videoViewCount", "videoPlayCount", "views", "viewCount"))
227
+ likes = _number(_first(row, "diggCount", "likesCount", "likes", "likeCount"))
228
+ comments_count = _number(_first(row, "commentCount", "commentsCount", "commentsTotal"))
229
+ shares = _number(_first(row, "shareCount", "sharesCount", "shares"))
230
+ saves = _number(_first(row, "collectCount", "saveCount", "savesCount", "saves"))
231
+ duration = _number(_first(row, "videoMeta.duration", "videoDuration", "duration"))
232
+ followers = _number(
233
+ _first(
234
+ row,
235
+ "authorMeta.fans",
236
+ "authorMeta.followers",
237
+ "ownerFollowersCount",
238
+ "followersCount",
239
+ "owner.followersCount",
240
+ )
241
+ )
242
+ if followers is None:
243
+ followers = _number(account.get("followers"))
244
+
245
+ sound_id = _text(
246
+ _first(
247
+ row,
248
+ "musicMeta.musicId",
249
+ "musicInfo.id",
250
+ "musicInfo.musicId",
251
+ "musicInfo.audio_id",
252
+ "audio.id",
253
+ )
254
+ )
255
+ sound_name = _text(
256
+ _first(
257
+ row,
258
+ "musicMeta.musicName",
259
+ "musicInfo.title",
260
+ "musicInfo.name",
261
+ "musicInfo.song_name",
262
+ "audio.name",
263
+ )
264
+ )
265
+ sound_author = _text(
266
+ _first(
267
+ row,
268
+ "musicMeta.musicAuthor",
269
+ "musicInfo.artist",
270
+ "musicInfo.author",
271
+ "musicInfo.artist_name",
272
+ "audio.author",
273
+ )
274
+ )
275
+ matched = sorted(
276
+ keyword
277
+ for keyword in account.get("product_keywords", [])
278
+ if keyword.casefold().lstrip("#") in caption.casefold()
279
+ or keyword.casefold().lstrip("#") in hashtags
280
+ )
281
+ paid_signals = [
282
+ marker for marker in AD_MARKERS
283
+ if (marker.lstrip("#") in hashtags if marker.startswith("#")
284
+ else marker in caption.casefold())
285
+ ]
286
+ if row.get("paidPartnership") is True:
287
+ paid_signals.append("provider-paid-partnership")
288
+
289
+ transcript = _text(
290
+ _first(row, "transcript", "subtitlesText", "subtitleText", "videoTranscript")
291
+ )
292
+ media_url = _text(
293
+ _first(
294
+ row,
295
+ "videoUrl",
296
+ "videoMeta.downloadAddr",
297
+ "videoMeta.playAddr",
298
+ "videoPlayUrl",
299
+ "downloadedVideo",
300
+ "downloadedVideoUrl",
301
+ )
302
+ )
303
+ if media_url is not None and not media_url.startswith(("https://", "http://")):
304
+ media_url = None
305
+ cover_url = _text(
306
+ _first(
307
+ row,
308
+ "displayUrl",
309
+ "coverUrl",
310
+ "videoMeta.coverUrl",
311
+ "videoMeta.cover",
312
+ "thumbnailUrl",
313
+ )
314
+ )
315
+ if cover_url is not None and not cover_url.startswith(("https://", "http://")):
316
+ cover_url = None
317
+ return {
318
+ "observation_id": f"{platform}:{video_id}",
319
+ "platform": platform,
320
+ "video_id": video_id,
321
+ "url": _canonical_url(platform, row, video_id, handle),
322
+ "account": {
323
+ "handle": handle,
324
+ "account_type": account["account_type"],
325
+ "followers": followers,
326
+ "collected_median_views": None,
327
+ },
328
+ "posted_at": posted.isoformat().replace("+00:00", "Z") if posted else None,
329
+ "age_days": age_days,
330
+ "caption": caption,
331
+ "hashtags": hashtags,
332
+ "metrics": {
333
+ "views": views,
334
+ "likes": likes,
335
+ "comments": comments_count,
336
+ "saves": saves,
337
+ "shares": shares,
338
+ "duration_seconds": duration,
339
+ },
340
+ "sound": {
341
+ "id": sound_id,
342
+ "name": sound_name,
343
+ "author": sound_author,
344
+ },
345
+ "comparisons": {},
346
+ "matched_keywords": matched,
347
+ "promotion_signals": sorted(set(paid_signals)),
348
+ "comments": _comments(row),
349
+ "evidence": {
350
+ "video_path": None,
351
+ "media_url": media_url,
352
+ "cover_url": cover_url,
353
+ "transcript": transcript,
354
+ "frame_paths": [],
355
+ "artifact_sha256": {},
356
+ "visual_preparation": None,
357
+ },
358
+ "selected_for_analysis": False,
359
+ }
360
+
361
+
362
+ def _prefer(left: Any, right: Any) -> Any:
363
+ if right is None or right == "" or right == [] or right == {}:
364
+ return left
365
+ if right == "unknown" and left not in (None, "", "unknown"):
366
+ return left
367
+ if left is None or left == "" or left == [] or left == {}:
368
+ return right
369
+ return right
370
+
371
+
372
+ def _merge(left: dict[str, Any], right: dict[str, Any]) -> dict[str, Any]:
373
+ result = json.loads(json.dumps(left))
374
+ for field in ("url", "posted_at", "age_days", "caption", "hashtags"):
375
+ result[field] = _prefer(result.get(field), right.get(field))
376
+ for section in ("account", "metrics", "sound"):
377
+ for field, value in right[section].items():
378
+ result[section][field] = _prefer(result[section].get(field), value)
379
+ for field in (
380
+ "video_path",
381
+ "media_url",
382
+ "cover_url",
383
+ "transcript",
384
+ "frame_paths",
385
+ "visual_preparation",
386
+ ):
387
+ result["evidence"][field] = _prefer(
388
+ result["evidence"].get(field), right["evidence"].get(field)
389
+ )
390
+ evidence_hashes = {
391
+ **(left["evidence"].get("artifact_sha256") or {}),
392
+ **(right["evidence"].get("artifact_sha256") or {}),
393
+ }
394
+ evidence_refs = (
395
+ ([result["evidence"]["video_path"]] if result["evidence"].get("video_path") else [])
396
+ + list(result["evidence"].get("frame_paths") or [])
397
+ )
398
+ result["evidence"]["artifact_sha256"] = {
399
+ relative: evidence_hashes[relative]
400
+ for relative in evidence_refs
401
+ if relative in evidence_hashes
402
+ }
403
+ result["comments"] = _merge_comments(result["comments"], right["comments"])
404
+ result["matched_keywords"] = sorted(
405
+ set(result["matched_keywords"])
406
+ | set(right["matched_keywords"])
407
+ )
408
+ result["promotion_signals"] = sorted(
409
+ set(result["promotion_signals"]) | set(right["promotion_signals"])
410
+ )
411
+ return result
412
+
413
+
414
+ def _describe_and_select(videos: list[dict[str, Any]], limit: int | None) -> list[str]:
415
+ """Describe the collected sample; never infer a winning format from ratios."""
416
+ grouped: dict[tuple[str, str], list[dict[str, Any]]] = {}
417
+ for video in videos:
418
+ grouped.setdefault((video["platform"], video["account"]["handle"]), []).append(video)
419
+ for account_videos in grouped.values():
420
+ views = [v["metrics"]["views"] for v in account_videos
421
+ if v["metrics"]["views"] is not None]
422
+ median = statistics.median(views) if views else None
423
+ for video in account_videos:
424
+ metrics = video["metrics"]
425
+ video["account"]["collected_median_views"] = median
426
+ video["comparisons"] = {
427
+ **{f"{metric}_per_view": _safe_ratio(metrics[metric], metrics["views"])
428
+ for metric in ("likes", "comments", "saves", "shares")},
429
+ "views_per_follower": _safe_ratio(metrics["views"], video["account"]["followers"]),
430
+ "vs_collected_account_median": _safe_ratio(metrics["views"], median),
431
+ }
432
+ # A requested resource cap is a deterministic sample, not a quality ranking.
433
+ groups = [sorted(grouped[key], key=lambda v: v["observation_id"])
434
+ for key in sorted(grouped)]
435
+ ordered = [group[index] for index in range(max(map(len, groups), default=0))
436
+ for group in groups if index < len(group)]
437
+ selected = ordered if limit is None else ordered[:limit]
438
+ selected_ids = {video["observation_id"] for video in selected}
439
+ for video in videos:
440
+ video["selected_for_analysis"] = video["observation_id"] in selected_ids
441
+ if len(selected) < len(videos):
442
+ return [f"Analysis resource cap selected {len(selected)} of {len(videos)} collected observations; "
443
+ "the account-balanced sample is not a performance ranking."]
444
+ return []
445
+
446
+
447
+ def _apply_collection_window(videos: list[dict[str, Any]], window: dict[str, Any]) -> list[str]:
448
+ lower = parse_rfc3339(window["oldest_post_date"] + "T00:00:00Z", "collection lower bound")
449
+ upper = parse_rfc3339(window["reference_at"], "collection reference_at")
450
+ counts = {"outside_window": 0, "unknown_date": 0}
451
+ for video in videos:
452
+ posted = _timestamp(video.get("posted_at"))
453
+ status = ("unknown_date" if posted is None else
454
+ "in_window" if lower <= posted <= upper else "outside_window")
455
+ video["time_window_status"] = status
456
+ if status in counts:
457
+ counts[status] += 1
458
+ gaps = []
459
+ if counts["outside_window"]:
460
+ gaps.append(f"Excluded {counts['outside_window']} observations outside the frozen collection window; raw evidence retained.")
461
+ if counts["unknown_date"]:
462
+ gaps.append(f"Excluded {counts['unknown_date']} observations with unknown publication dates from the time-window sample; raw evidence retained.")
463
+ return gaps
464
+
465
+
466
+ def _discovery_sources(manifest: dict[str, Any]) -> list[dict[str, str]]:
467
+ return sorted(
468
+ [
469
+ {"path": item["path"], "sha256": item["sha256"]}
470
+ for item in manifest["datasets"]
471
+ if item["kind"] == "discovery"
472
+ ],
473
+ key=lambda item: item["path"],
474
+ )
475
+
476
+
477
+ def _freeze_selection(
478
+ root: Path,
479
+ manifest: dict[str, Any],
480
+ videos: list[dict[str, Any]],
481
+ computed_gaps: list[str],
482
+ window: dict[str, Any],
483
+ ) -> tuple[list[str], dict[str, str]]:
484
+ path = root / "normalized/selection.json"
485
+ current_sources = _discovery_sources(manifest)
486
+ by_id = {video["observation_id"]: video for video in videos}
487
+ if path.is_file():
488
+ value = read_json(path)
489
+ if value.get("schema_version") != SCHEMA_VERSION:
490
+ raise ContractError("selection schema_version must be 1")
491
+ if value.get("collection_epoch") != manifest["collection_epoch"]:
492
+ raise ContractError("selection belongs to a different collection epoch")
493
+ if value.get("discovery_sources") != current_sources:
494
+ raise ContractError("selection discovery evidence changed")
495
+ if value.get("collection_window") != window:
496
+ raise ContractError("selection collection window changed")
497
+ selected_ids = value.get("selected_observation_ids")
498
+ selection_gaps = value.get("selection_gaps")
499
+ if (
500
+ not isinstance(selected_ids, list)
501
+ or len(selected_ids) != len(set(selected_ids))
502
+ or not all(isinstance(item, str) and item in by_id
503
+ and by_id[item]["time_window_status"] == "in_window"
504
+ for item in selected_ids)
505
+ ):
506
+ raise ContractError("selection contains invalid observation IDs")
507
+ if (
508
+ not isinstance(selection_gaps, list)
509
+ or selection_gaps != sorted(selection_gaps)
510
+ or not all(isinstance(item, str) and item.strip() for item in selection_gaps)
511
+ ):
512
+ raise ContractError("selection gaps are invalid")
513
+ else:
514
+ if any(item["kind"] == "enrichment" for item in manifest["datasets"]):
515
+ raise ContractError(
516
+ "normalize discovery and freeze selection before collecting enrichment"
517
+ )
518
+ selected_ids = sorted(
519
+ video["observation_id"]
520
+ for video in videos
521
+ if video["selected_for_analysis"]
522
+ )
523
+ selection_gaps = sorted(computed_gaps)
524
+ atomic_write_json(
525
+ path,
526
+ {
527
+ "schema_version": SCHEMA_VERSION,
528
+ "collection_epoch": manifest["collection_epoch"],
529
+ "discovery_sources": current_sources,
530
+ "collection_window": window,
531
+ "selected_observation_ids": selected_ids,
532
+ "selection_gaps": selection_gaps,
533
+ },
534
+ )
535
+ selected_set = set(selected_ids)
536
+ for video in videos:
537
+ video["selected_for_analysis"] = video["observation_id"] in selected_set
538
+ return selection_gaps, {
539
+ "path": "normalized/selection.json",
540
+ "sha256": sha256_file(path),
541
+ }
542
+
543
+
544
+ def normalize(root: Path) -> dict[str, Any]:
545
+ context = validate_context(root / "context.json")
546
+ state = load_run_state(root)
547
+ window = validate_collection_window(context, state.get("collection_window"))
548
+ manifest = validate_raw_manifest(root)
549
+ collected_at = parse_rfc3339(
550
+ manifest["collection_completed_at"], "collection_completed_at"
551
+ )
552
+ accounts: dict[tuple[str, str], dict[str, Any]] = {}
553
+ for item in manifest["accounts"]:
554
+ copy = dict(item)
555
+ copy["handle"] = _handle(item["handle"])
556
+ copy["product_keywords"] = sorted(
557
+ {keyword.casefold().lstrip("#") for keyword in item["product_keywords"]}
558
+ )
559
+ accounts[(item["platform"], copy["handle"])] = copy
560
+
561
+ linked_tiktok_comments: dict[str, list[dict[str, Any]]] = {}
562
+ if any(
563
+ item.get("platform") == "tiktok" and item.get("kind") == "enrichment"
564
+ for item in manifest["datasets"]
565
+ ):
566
+ main_payload = read_json(root / "raw/tiktok-enrichment.json")
567
+ linked_bundle = read_json(root / TIKTOK_COMMENTS_BUNDLE_PATH)
568
+ linked_tiktok_comments = validate_linked_tiktok_comments_bundle(
569
+ main_payload,
570
+ linked_bundle,
571
+ )
572
+
573
+ normalized: dict[str, dict[str, Any]] = {}
574
+ datasets = sorted(manifest["datasets"], key=lambda item: item["kind"] == "enrichment")
575
+ for dataset in datasets:
576
+ source_path = resolve_relative(root, dataset["path"], "dataset.path")
577
+ try:
578
+ raw_value = json.loads(source_path.read_text(encoding="utf-8"))
579
+ except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
580
+ raise ContractError(f"cannot read raw dataset {dataset['path']}: {exc}") from exc
581
+ for row in extract_rows(raw_value):
582
+ video = _normalize_row(
583
+ platform=dataset["platform"],
584
+ row=row,
585
+ accounts=accounts,
586
+ collected_at=collected_at,
587
+ )
588
+ if video is None:
589
+ continue
590
+ if video["platform"] == "tiktok":
591
+ linked_rows = linked_tiktok_comments.get(video["video_id"], [])
592
+ if linked_rows:
593
+ video["comments"] = _merge_comments(
594
+ video["comments"],
595
+ _comments({"comments": linked_rows}),
596
+ )
597
+ existing = normalized.get(video["observation_id"])
598
+ normalized[video["observation_id"]] = video if existing is None else _merge(existing, video)
599
+ videos = list(normalized.values())
600
+ computed_gaps = _apply_collection_window(videos, window)
601
+ eligible = [video for video in videos if video["time_window_status"] == "in_window"]
602
+ computed_gaps.extend(_describe_and_select(eligible, context.get("max_analysis_videos", 30)))
603
+ selection_gaps, selection_source = _freeze_selection(
604
+ root, manifest, videos, computed_gaps, window
605
+ )
606
+ videos.sort(
607
+ key=lambda video: (
608
+ video["platform"],
609
+ video["account"]["handle"],
610
+ not video["selected_for_analysis"],
611
+ video["observation_id"],
612
+ )
613
+ )
614
+ return {
615
+ "schema_version": SCHEMA_VERSION,
616
+ "analysis_contract_version": ANALYSIS_CONTRACT_VERSION,
617
+ "generated_at": manifest["collection_completed_at"],
618
+ "source_manifest_sha256": sha256_file(root / "raw/manifest.json"),
619
+ "selection_source": selection_source,
620
+ "selection_gaps": selection_gaps,
621
+ "collection_window": window,
622
+ "time_window_counts": {
623
+ status: sum(video["time_window_status"] == status for video in videos)
624
+ for status in ("in_window", "outside_window", "unknown_date")
625
+ },
626
+ "videos": videos,
627
+ }
628
+
629
+
630
+ def main() -> int:
631
+ parser = argparse.ArgumentParser()
632
+ parser.add_argument("--runtime-root", type=Path, required=True)
633
+ args = parser.parse_args()
634
+ root = args.runtime_root.resolve()
635
+ try:
636
+ payload = normalize(root)
637
+ atomic_write_json(root / "normalized/videos.json", payload)
638
+ except (ContractError, OSError) as exc:
639
+ print(f"organic trend normalization failed: {exc}", file=sys.stderr)
640
+ return 1
641
+ selected = sum(bool(video["selected_for_analysis"]) for video in payload["videos"])
642
+ print(f"normalized {len(payload['videos'])} videos; selected {selected}")
643
+ return 0
644
+
645
+
646
+ if __name__ == "__main__":
647
+ raise SystemExit(main())