@0xward/cultos-utils 1.0.5 → 1.0.7

package/LICENSE

@@ -2,4 +2,20 @@ MIT License
 
 Copyright (c) 2026 0xward
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files, to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software... Full MIT Granted.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/index.js

@@ -1,7 +1,151 @@
-// CultOS Utilities - AI meme coin generator framework for Stacks
+// @0xward/cultos-utils
+// AI-powered meme coin generator framework for the Stacks ecosystem (Bitcoin L2)
+// SIP-10 compliant token metadata, viral factor scoring, and cult mechanics
+
+const SIP10_STANDARD       = "SIP-010";
+const STACKS_ECOSYSTEM     = "Stacks Bitcoin L2";
+const DEFAULT_SUPPLY       = "1000000000";
+const MAX_TICKER_LENGTH    = 8;
+const MIN_TICKER_LENGTH    = 2;
+const MAX_NAME_LENGTH      = 64;
+
+const CULT_ARCHETYPES = {
+    degen:   { viralMultiplier: 1.8, description: "High risk, high reward degenerate energy"  },
+    meme:    { viralMultiplier: 2.0, description: "Pure internet culture and meme propagation" },
+    oracle:  { viralMultiplier: 1.5, description: "Mystical on-chain prophecy narrative"       },
+    rebel:   { viralMultiplier: 1.6, description: "Anti-establishment movement energy"         },
+    cosmic:  { viralMultiplier: 1.7, description: "Universal and transcendental branding"      },
+};
+
+const TOKENOMICS_PRESETS = {
+    fair:    { community: 80, team: 10, treasury: 10 },
+    stealth: { community: 95, team: 0,  treasury: 5  },
+    vested:  { community: 60, team: 20, treasury: 20 },
+};
+
 class CultOSUtils {
-    static generateMemeMetadata(name, ticker) {
-        return { name: name, ticker: ticker, supply: "1000000000", sip10Standard: true, ecosystem: "Stacks Bitcoin L2" };
+    constructor(options = {}) {
+        this.ecosystem  = options.ecosystem  || STACKS_ECOSYSTEM;
+        this.standard   = options.standard   || SIP10_STANDARD;
+        this.version    = "1.0.7";
+    }
+
+    _validateTicker(ticker) {
+        if (typeof ticker !== "string" || ticker.trim().length === 0) {
+            throw new Error("ticker must be a non-empty string.");
+        }
+        const clean = ticker.trim().toUpperCase();
+        if (clean.length < MIN_TICKER_LENGTH || clean.length > MAX_TICKER_LENGTH) {
+            throw new Error(
+                `ticker must be ${MIN_TICKER_LENGTH}–${MAX_TICKER_LENGTH} characters. Got: "${clean}" (${clean.length})`
+            );
+        }
+        if (!/^[A-Z0-9]+$/.test(clean)) {
+            throw new Error(`ticker must only contain uppercase letters and digits. Got: "${clean}"`);
+        }
+        return clean;
+    }
+
+    _validateName(name) {
+        if (typeof name !== "string" || name.trim().length === 0) {
+            throw new Error("name must be a non-empty string.");
+        }
+        if (name.trim().length > MAX_NAME_LENGTH) {
+            throw new Error(`name must not exceed ${MAX_NAME_LENGTH} characters.`);
+        }
+        return name.trim();
+    }
+
+    _validateSupply(supply) {
+        const s = String(supply || DEFAULT_SUPPLY).replace(/_/g, "");
+        if (!/^\d+$/.test(s) || BigInt(s) <= 0n) {
+            throw new Error(`supply must be a positive integer string. Got: "${supply}"`);
+        }
+        return s;
+    }
+
+    _computeViralScore(archetype, supply, nameLength) {
+        const base      = CULT_ARCHETYPES[archetype]?.viralMultiplier || 1.0;
+        const supplyNum = Math.log10(parseFloat(supply) || 1);
+        const namePenalty = nameLength > 20 ? 0.9 : 1.0;
+        const raw = base * (supplyNum / 10) * namePenalty * 100;
+        return Math.min(Math.round(raw), 100);
+    }
+
+    static generateMemeMetadata(name, ticker, options = {}) {
+        const instance = new CultOSUtils(options);
+        return instance.generateMemeMetadata(name, ticker, options);
+    }
+
+    generateMemeMetadata(name, ticker, options = {}) {
+        const validName    = this._validateName(name);
+        const validTicker  = this._validateTicker(ticker);
+        const supply       = this._validateSupply(options.supply);
+        const archetype    = options.archetype || "meme";
+        const decimals     = options.decimals  ?? 6;
+        const preset       = options.tokenomics || "fair";
+
+        if (!CULT_ARCHETYPES[archetype]) {
+            throw new Error(
+                `Unknown archetype: "${archetype}". Use: ${Object.keys(CULT_ARCHETYPES).join(", ")}.`
+            );
+        }
+        if (!TOKENOMICS_PRESETS[preset]) {
+            throw new Error(
+                `Unknown tokenomics preset: "${preset}". Use: ${Object.keys(TOKENOMICS_PRESETS).join(", ")}.`
+            );
+        }
+
+        const viralScore   = this._computeViralScore(archetype, supply, validName.length);
+        const tokenomics   = TOKENOMICS_PRESETS[preset];
+        const cultMeta     = CULT_ARCHETYPES[archetype];
+
+        return {
+            name:          validName,
+            ticker:        validTicker,
+            supply,
+            decimals,
+            sip10Standard: this.standard,
+            ecosystem:     this.ecosystem,
+            securedBy:     "Bitcoin",
+            archetype,
+            archetypeDescription: cultMeta.description,
+            viralScore,
+            viralRating:   viralScore >= 80 ? "Viral" : viralScore >= 50 ? "Growing" : "Niche",
+            tokenomics: {
+                preset,
+                communityPercent: tokenomics.community,
+                teamPercent:      tokenomics.team,
+                treasuryPercent:  tokenomics.treasury,
+            },
+            generatedAt:   new Date().toISOString(),
+            sdkVersion:    this.version,
+        };
+    }
+
+    computeViralFactor(metadata) {
+        if (!metadata || typeof metadata !== "object") {
+            throw new Error("metadata must be a valid object.");
+        }
+        if (!metadata.ticker || !metadata.name) {
+            throw new Error("metadata must include 'ticker' and 'name'.");
+        }
+        const archetype  = metadata.archetype || "meme";
+        const supply     = metadata.supply    || DEFAULT_SUPPLY;
+        return this._computeViralScore(archetype, supply, metadata.name.length);
+    }
+
+    getCultArchetypes() {
+        return Object.entries(CULT_ARCHETYPES).map(([key, val]) => ({ id: key, ...val }));
+    }
+
+    getTokenomicsPresets() {
+        return Object.entries(TOKENOMICS_PRESETS).map(([key, val]) => ({ id: key, ...val }));
+    }
+
+    getVersion() {
+        return this.version;
     }
 }
-module.exports = { CultOSUtils };
+
+module.exports = { CultOSUtils, CULT_ARCHETYPES, TOKENOMICS_PRESETS, SIP10_STANDARD };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xward/cultos-utils",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Futuristic AI-powered generator framework for viral internet-style cult meme coins in the Stacks ecosystem.",
   "main": "index.js",
   "keywords": [
@@ -20,5 +20,10 @@
   "bugs": {
     "url": "https://github.com/0xward/cultos-utils/issues"
   },
-  "homepage": "https://www.npmjs.com/package/@0xward/cultos-utils#readme"
+  "homepage": "https://www.npmjs.com/package/@0xward/cultos-utils#readme",
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ]
 }

package/.github/workflows/generator-generic-ossf-slsa3-publish.yml

@@ -1,66 +0,0 @@
-# This workflow uses actions that are not certified by GitHub.
-# They are provided by a third-party and are governed by
-# separate terms of service, privacy policy, and support
-# documentation.
-
-# This workflow lets you generate SLSA provenance file for your project.
-# The generation satisfies level 3 for the provenance requirements - see https://slsa.dev/spec/v0.1/requirements
-# The project is an initiative of the OpenSSF (openssf.org) and is developed at
-# https://github.com/slsa-framework/slsa-github-generator.
-# The provenance file can be verified using https://github.com/slsa-framework/slsa-verifier.
-# For more information about SLSA and how it improves the supply-chain, visit slsa.dev.
-
-name: SLSA generic generator
-on:
-  workflow_dispatch:
-  release:
-    types: [created]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    outputs:
-      digests: ${{ steps.hash.outputs.digests }}
-
-    steps:
-      - uses: actions/checkout@v4
-
-      # ========================================================
-      #
-      # Step 1: Build your artifacts.
-      #
-      # ========================================================
-      - name: Build artifacts
-        run: |
-            # These are some amazing artifacts.
-            echo "artifact1" > artifact1
-            echo "artifact2" > artifact2
-
-      # ========================================================
-      #
-      # Step 2: Add a step to generate the provenance subjects
-      #         as shown below. Update the sha256 sum arguments
-      #         to include all binaries that you generate
-      #         provenance for.
-      #
-      # ========================================================
-      - name: Generate subject for provenance
-        id: hash
-        run: |
-          set -euo pipefail
-
-          # List the artifacts the provenance will refer to.
-          files=$(ls artifact*)
-          # Generate the subjects (base64 encoded).
-          echo "hashes=$(sha256sum $files | base64 -w0)" >> "${GITHUB_OUTPUT}"
-
-  provenance:
-    needs: [build]
-    permissions:
-      actions: read   # To read the workflow path.
-      id-token: write # To sign the provenance.
-      contents: write # To add assets to a release.
-    uses: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@v1.4.0
-    with:
-      base64-subjects: "${{ needs.build.outputs.digests }}"
-      upload-assets: true # Optional: Upload to a new release

package/assets/header-sync.svg

@@ -1,14 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" width="120" height="120">
-  <style>
-    .layer { fill: none; stroke: #888888; stroke-width: 2; transform-origin: center; }
-    .l1 { animation: slide 3s ease-in-out infinite; }
-    .l2 { animation: slide 3s ease-in-out infinite; animation-delay: 1s; }
-    .l3 { animation: slide 3s ease-in-out infinite; animation-delay: 2s; }
-    @keyframes slide { 0%, 100% { transform: translateY(0px) scale(0.9); opacity: 0.4; } 50% { transform: translateY(-5px) scale(1); opacity: 0.9; } }
-  </style>
-  <g>
-    <polygon points="50,20 80,35 50,50 20,35" class="layer l1" />
-    <polygon points="50,40 80,55 50,70 20,55" class="layer l2" />
-    <polygon points="50,60 80,75 50,90 20,75" class="layer l3" />
-  </g>
-</svg>

package/examples/basic-demo.js

@@ -1,5 +0,0 @@
-const { CultOSUtils } = require("../index.js");
-console.log("🚀 Generating Cult Meme Coin Metadata on Stacks...");
-const meta = CultOSUtils.generateMemeMetadata("WAGMI Cult", "WAGMIC");
-console.log("Metadata Created:", meta);
-console.log("✅ [cultos-utils] Demo running successfully!");