Add Architecture Analysis and Evolution Roadmap

.github/workflows/auto-bump-version.yml

@@ -34,7 +34,7 @@ jobs:
         run: |
           set -euo pipefail
           BEFORE=$(node -e "console.log(require('./package.json').version)")
-          node scripts/bump-version.mjs
+          node --experimental-strip-types scripts/bump-version.ts
           AFTER=$(node -e "console.log(require('./package.json').version)")
           echo "before=$BEFORE" >> "$GITHUB_OUTPUT"
           echo "after=$AFTER" >> "$GITHUB_OUTPUT"

.github/workflows/release-content.yml

@@ -49,11 +49,11 @@ jobs:
         run: bun run validate:content
 
       - name: Build release bundles
-        run: node scripts/build-release-bundles.mjs --version "${{ steps.ver.outputs.version }}"
+        run: node --experimental-strip-types scripts/build-release-bundles.ts --version "${{ steps.ver.outputs.version }}"
 
       - name: Generate changelog
         run: |
-          node scripts/generate-changelog.mjs \
+          node --experimental-strip-types scripts/generate-changelog.ts \
             --version "${{ steps.ver.outputs.version }}" \
             --out dist/release/CHANGELOG.md
 

.github/workflows/skillspector.yml

@@ -17,7 +17,7 @@ on:
       - "content/playbooks/**"
       - "content/souls/**"
       - "content/integrations/**"
-      - "scripts/scan-skillspector.mjs"
+      - "scripts/scan-skillspector.ts"
       - ".github/workflows/skillspector.yml"
 
 permissions:
@@ -75,7 +75,7 @@ jobs:
           SKILLSPECTOR_LOG_LEVEL: ERROR
         run: |
           # Static analysis only — no LLM provider key needed in CI.
-          node scripts/scan-skillspector.mjs ${{ steps.changed.outputs.files }} \
+          node --experimental-strip-types scripts/scan-skillspector.ts ${{ steps.changed.outputs.files }} \
             --sarif skillspector.sarif
 
       - name: Upload SARIF to code scanning

.github/workflows/test.yml

@@ -15,20 +15,20 @@ jobs:
       - run: npm ci
       - name: Plain node:test suites
         run: |
-          node --test \
-            tests/adversarial-harness.test.mjs \
-            tests/trust.test.mjs \
-            tests/release-signing.test.mjs \
-            tests/cli-install.test.mjs
+          node --experimental-strip-types --test \
+            tests/adversarial-harness.test.ts \
+            tests/trust.test.ts \
+            tests/release-signing.test.ts \
+            tests/cli-install.test.ts
       - name: TypeScript-source node:test suites
         run: |
           node --experimental-strip-types --test \
-            tests/prompt-injection-guard.test.mjs \
-            tests/runtime.test.mjs \
-            tests/integrations.test.mjs \
-            tests/growth-revenue-split.test.mjs \
-            tests/trust-badge.test.mjs \
-            tests/bounties.test.mjs \
-            tests/trust-scoring.test.mjs \
-            tests/adversarial-holdout.test.mjs \
-            tests/adversarial-judge.test.mjs
+            tests/prompt-injection-guard.test.ts \
+            tests/runtime.test.ts \
+            tests/integrations.test.ts \
+            tests/growth-revenue-split.test.ts \
+            tests/trust-badge.test.ts \
+            tests/bounties.test.ts \
+            tests/trust-scoring.test.ts \
+            tests/adversarial-holdout.test.ts \
+            tests/adversarial-judge.test.ts

.github/workflows/validate-content.yml

@@ -4,20 +4,20 @@ on:
   pull_request:
     paths:
       - "content/**"
-      - "scripts/validate-content.mjs"
-      - "scripts/audit-skills.mjs"
-      - "scripts/build-skills-sh-mirror.mjs"
-      - "scripts/build-agent-plugin.mjs"
+      - "scripts/validate-content.ts"
+      - "scripts/audit-skills.ts"
+      - "scripts/build-skills-sh-mirror.ts"
+      - "scripts/build-agent-plugin.ts"
       - "src/lib/security/prompt-injection-guard.ts"
       - ".github/workflows/validate-content.yml"
   push:
     branches: [main]
     paths:
       - "content/**"
-      - "scripts/validate-content.mjs"
-      - "scripts/audit-skills.mjs"
-      - "scripts/build-skills-sh-mirror.mjs"
-      - "scripts/build-agent-plugin.mjs"
+      - "scripts/validate-content.ts"
+      - "scripts/audit-skills.ts"
+      - "scripts/build-skills-sh-mirror.ts"
+      - "scripts/build-agent-plugin.ts"
       - "src/lib/security/prompt-injection-guard.ts"
 
 jobs:

ANALYSIS.md

@@ -0,0 +1,50 @@
+# Super Agent Skill: Architecture Analysis & Evolution Roadmap
+
+## 1. Current Architecture Overview
+
+Super Agent Skill is a platform for distributing AI agent capabilities (skills, playbooks, souls, guardrails) with a strong emphasis on security, adversarial robustness, and trust scoring.
+
+### Core Stack
+- **Frontend & API:** TanStack Start, React 19, Tailwind CSS v4, Radix UI. It acts as both the marketing site, the user dashboard, and hosts the public/private APIs.
+- **Database:** Supabase (PostgreSQL) handling data storage, Row Level Security (RLS), and full-text search (`search_vector` with `tsvector`).
+- **Distribution:**
+  - **MCP (Model Context Protocol):** Provides a standard API for AI assistants to discover and install packages.
+  - **CLI (`packages/cli`):** A Node.js CLI tool (`super-agent.mjs`) to install skills directly.
+  - **File downloads:** YAML manifests directly available.
+- **Content:** The `content/` directory contains the "open seed" of YAML files describing skills.
+- **Evaluation Engine (SkillForge):** Custom adversarial harness scripts (in `scripts/`) to test skills against prompt injection, data exfiltration, policy bypass, etc.
+- **Tests:** A custom plain Node test runner (`node --test`) testing both adversarial scripts and site functionality.
+
+### Strengths
+1. **Security-First Approach:** Deep integration of adversarial testing (injection, role hijack, data leaks).
+2. **Trust Architecture:** Cryptographic signing of packages and attestations, providing verifiable offline trust.
+3. **Distribution Agnostic:** Support for MCP, CLI, and raw files gives great flexibility to end-users.
+4. **Modern Stack:** TanStack Start and React 19 provide a solid, fast SSR foundation.
+
+---
+
+## 2. Identified Areas for Improvement & Evolution
+
+### A. Codebase & Tooling Standardization
+- **Script Migration:** The `scripts/` directory contains a mix of `.mjs` scripts (e.g., `audit-skills.mjs`, `eval-adversarial.mjs`). Migrating these to TypeScript would improve type safety, maintainability, and alignment with the main app code.
+- **Monorepo Structure:** The `packages/cli` is partially separated but still relies on root dependencies. Formalizing a monorepo structure (e.g., using Turborepo or npm workspaces) for `web`, `cli`, and `core` packages would improve dependency management.
+- **Test Framework:** The current Node.js built-in test runner (`node --test`) works, but migrating to Vitest would provide better integration with Vite/TanStack Start, better mocking, and UI for tests.
+
+### B. Security & Integrity Enhancements
+- **End-to-End Test Automation:** Implement Playwright/Cypress tests for critical user flows (OAuth login, package upload, CLI interaction).
+- **Automated Signature Rotation:** Implement automated key rotation and revocation lists for package signatures.
+- **Vector Search Tuning:** The `tsvector` search is currently basic. Integrating pgvector for semantic search over skill descriptions would significantly improve the discovery experience in the marketplace.
+
+### C. Developer & Author Experience (SkillForge)
+- **CLI Expansion:** Implement the planned `sas init`, `sas publish`, and `sas eval` commands in the CLI to allow authors to build and test locally before uploading.
+- **Versioned Bundles:** Build out the versioned downloadable registry bundles mentioned in the roadmap.
+- **Curated Collections:** Implement the UI and data model for community-curated bundles around specific use cases.
+
+### D. Architecture Scalability
+- **Evaluation Queueing:** The adversarial evaluation (`eval-adversarial.mjs`) seems to run synchronously or in basic scripts. As the registry grows, moving this to a robust background job queue (e.g., BullMQ or temporal.io) is critical.
+- **Caching Layer:** The API and SSR currently rely on Cloudflare/Vite caches. Introducing Redis for aggressive caching of trust scores and package metadata could reduce DB load.
+
+## 3. Recommended Next Steps (Short-term)
+1. **Implement `pgvector` for Semantic Search:** Enhance the marketplace discovery.
+2. **Migrate `.mjs` Scripts to TypeScript:** Reduce technical debt in the build and eval pipelines.
+3. **Flesh out the CLI:** Add `init` and `publish` commands for developers.

cli/package.json

@@ -4,19 +4,20 @@
   "description": "Plug-and-play Super Agent Skill MCP: OAuth login, client auto-config, local stdio bridge, and skill package install for Claude / Cursor / Codex / VS Code / Windsurf.",
   "type": "module",
   "bin": {
-    "super-agent": "./super-agent.mjs"
+    "super-agent": "./super-agent.js"
   },
   "files": [
-    "super-agent.mjs",
+    "super-agent.js",
     "README.md"
   ],
   "scripts": {
+    "prebuild:bin": "bun build ./super-agent.ts --target=node --outfile=super-agent.js",
     "build:bin": "npx -y @yao-pkg/pkg . --targets node20-linux-x64,node20-macos-x64,node20-macos-arm64,node20-win-x64 --out-path dist",
-    "build:bun": "bun build ./super-agent.mjs --compile --outfile dist/super-agent"
+    "build:bun": "bun build ./super-agent.ts --compile --outfile dist/super-agent"
   },
   "pkg": {
     "scripts": [
-      "super-agent.mjs"
+      "super-agent.js"
     ],
     "outputPath": "dist"
   },