cbs-block 1.0.6 → 1.0.8

package/README.md

@@ -1,55 +1,84 @@
-# cbs-block SDK 🚀
+# 🚀 CodeBlock Studio SDK (CLI)
 
-The official toolkit for building **CodeBlock Studio** extensions. Create, package, and share powerful visual blocks with ease.
+The professional toolkit for building, testing, and sharing **CodeBlock Studio** extensions. 
+
+Built for performance. Designed for developers.
+
+---
 
 ## 📦 Installation
 
-Install the CLI globally to use the `cbs-block` command anywhere:
+Install globally to use the `cbs-block` command anywhere:
 
 ```bash
 npm install cbs-block -g
 ```
 
+## 🛠️ Feature Highlights
+
+*   **Code-First Workflow**: Build complex blocks with full folder structures, supporting `index.js/ts`, `package.json`, and local `node_modules`.
+*   **Integrated Unit Testing**: Run logic tests instantly with `cbs-block test`.
+*   **Micro-Benchmarking**: Performance-test your logic with `cbs-block bench` (100k iteration analysis).
+*   **Integrated Tutorials**: Every new project includes a beautiful, CSS-rich `tutorial.html`. View it via `cbs-block tutorial`.
+*   **VSIX-Style Packaging**: Bundle your workspace into a professional `.cbsext` extension with one command.
+
+---
+
 ## 🚀 Quick Start
 
 ### 1. Initialize a Project
 Create a new workspace for your block library:
 ```bash
-cbs-block init MyAwesomeBlocks
-cd MyAwesomeBlocks
+cbs-block init MyAwesomePack
+cd MyAwesomePack
 ```
 
-### 2. Create your First Block
-Generate a template for a new block. Choose a category like `Math`, `Logic`, or `Control`:
+### 2. Create a Block
+Generate a professional directory-based block:
 ```bash
-cbs-block create SimpleAdd Math
+cbs-block create MyBlock
 ```
 
-### 3. Build & Package
-When you're ready to share, bundle your blocks into a `.cbspak` file:
+### 3. Develop & Test
+Open `index.js`, write your logic, and test it:
 ```bash
 cbs-block build
+cbs-block test myblock.cbsblock
 ```
 
+### 4. Pack & Share
+Bundle your workspace into a professional extension:
+```bash
+cbs-block pack
+```
+
+---
+
 ## 🛠️ Command Reference
 
 | Command | Description |
 | --- | --- |
-| `init <Name>` | Creates a new block development workspace. |
-| `create <Name> [Category]` | Generates a new `.cbsblock` template. |
-| `list` | Lists all blocks in the current directory. |
-| `lint` | Validates your blocks against the Studio schema. |
-| `build` | Packages your project into a `.cbspak` for the marketplace. |
-| `serve` | Starts a local hot-reload server for real-time testing. |
-| `publish` | Deploys your package to the CBS Marketplace. |
-
-## 🧩 What is a .cbsblock?
-A block is a JSON file that defines its visuals and its logic.
-- **Visuals**: Ports (Input/Output/Flow) and interactive fields.
-- **Logic**: A sandboxed JavaScript function that executes within the Studio.
-
-## 🔒 The CBS Ecosystem
-Note: `.cbspak` and `.cbsblock` files are proprietary formats optimized for **CodeBlock Studio**. They cannot be opened in standard text editors or other IDEs without the CBS engine.
+| `init [name]` | Initialize a new block project workspace. |
+| `create [name]` | Scaffold a new block (supports Directory or Single-File mode). |
+| `build [dir]` | Compile a directory block into a production `.cbsblock`. |
+| `pack` | Bundle your workspace into a professional `.cbsext` extension. |
+| `test <file>` | Run logic unit tests with mock data. |
+| `bench <file>` | Benchmark block logic performance (iterations & μs). |
+| `tutorial` | Open the integrated developer guide in your browser. |
+| `link` | Link local blocks to your CodeBlock Studio installation. |
+| `publish` | Deploys your package to the global CBS Marketplace. |
+| `site` | Generate a themed documentation website for your project. |
+| `doc <file>` | Generate a markdown README for a specific block. |
+| `lint` | Validate block definitions for schema compliance. |
+| `status` | Check SDK version and environment health. |
+
+---
+
+## 🧩 The .cbsext Format
+Professional extensions are packaged as ZIP-based `.cbsext` files. This allows for:
+- **Rich Assets**: Bundle icons, helper scripts, and HTML tutorials into one file.
+- **Enterprise Metadata**: Verified publisher IDs and display names.
+- **Dependency Isolation**: Fully bundled logic with optimized execution.
 
 ---
-**Build the future of visual coding with CodeBlock Studio.**
+**Build the future of visual coding with [CodeBlock Studio](https://codeblockstudio.web.app).**

package/bin/cbs-block.js

@@ -3,7 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const chalk = require('chalk');
-const { execSync } = require('child_process');
+const { execSync, exec } = require('child_process');
 
 async function main() {
     const { default: inquirer } = await import('inquirer');
@@ -14,13 +14,15 @@ async function main() {
 
     if (command === 'create') {
         const answers = await inquirer.prompt([
-            { type: 'input', name: 'name', message: 'Block name:', default: target || 'MyBlock' },
+            { type: 'input', name: 'name', message: 'Internal ID (no spaces):', default: target || 'my-block' },
+            { type: 'input', name: 'displayName', message: 'Display Name:', default: (a) => a.name },
+            { type: 'input', name: 'publisher', message: 'Publisher:', default: 'cbs-creator' },
             { type: 'list', name: 'category', message: 'Category:', choices: ['Math', 'Logic', 'Control', 'Input', 'Output', 'Data', 'Custom'] },
             { type: 'input', name: 'color', message: 'Hex Color:', default: (a) => {
                 const colors = { 'Math': '#4A90E2', 'Logic': '#F5A623', 'Control': '#FFCC00', 'Custom': '#4CAF50' };
                 return colors[a.category] || '#4CAF50';
             }},
-            { type: 'confirm', name: 'useDir', message: 'Create as directory (Recommended for external packages)?', default: true },
+            { type: 'confirm', name: 'useDir', message: 'Create as directory (Professional Extension Mode)?', default: true },
             { type: 'list', name: 'lang', message: 'Primary Language:', choices: ['JavaScript', 'TypeScript'] }
         ]);
 
@@ -54,14 +56,28 @@ async function main() {
             fs.writeFileSync(path.join(dirName, answers.lang === 'TypeScript' ? 'index.ts' : 'index.js'), logicStr);
             fs.writeFileSync(path.join(dirName, 'package.json'), JSON.stringify({
                 name: dirName,
+                displayName: answers.displayName,
+                publisher: answers.publisher,
                 version: "1.0.0",
                 main: "index.js",
+                engines: { "cbs": ">=1.1.0" },
                 dependencies: {}
             }, null, 2));
 
+            // NEW: Copy templates
+            const templateDir = path.join(__dirname, '../templates');
+            if (fs.existsSync(templateDir)) {
+                ['tutorial.html', 'README.md'].forEach(file => {
+                    let content = fs.readFileSync(path.join(templateDir, file), 'utf8');
+                    content = content.replace(/{BLOCK_NAME}/g, answers.name);
+                    fs.writeFileSync(path.join(dirName, file), content);
+                });
+                fs.writeFileSync(path.join(dirName, 'LICENSE'), `MIT License\n\nCopyright (c) 2026 ${answers.name} Author`);
+            }
+
             console.log(chalk.green(`\n✔ Created code-first block directory: ${chalk.bold(dirName)}`));
             console.log(chalk.cyan(`   → cd ${dirName}`));
-            console.log(chalk.cyan(`   → npm install <your-package>`));
+            console.log(chalk.cyan(`   → cbs-block tutorial  (View the guide!)`));
             console.log(chalk.cyan(`   → cbs-block build`));
 
         } else {
@@ -136,31 +152,29 @@ async function main() {
         console.log(chalk.green(`\n✔ Project ${chalk.bold(answers.projName)} initialized!`));
 
     } else if (command === 'pack') {
-        const files = fs.readdirSync('.').filter(f => f.endsWith('.cbsblock'));
-        const dirs = fs.readdirSync('.').filter(d => fs.statSync(d).isDirectory() && fs.existsSync(path.join(d, 'metadata.json')));
-        
-        console.log(chalk.yellow(`Packing ${files.length} files and ${dirs.length} directories into a .cbspak...`));
+        const pkgPath = path.join(process.cwd(), 'package.json');
+        if (!fs.existsSync(pkgPath)) {
+            // Legacy/Single-file packing (keeping for compatibility)
+            const files = fs.readdirSync('.').filter(f => f.endsWith('.cbsblock'));
+            const pack = { package: path.basename(process.cwd()), version: "1.0.4", blocks: files.map(f => JSON.parse(fs.readFileSync(f, 'utf8'))) };
+            fs.writeFileSync(`${pack.package}.cbspak`, JSON.stringify(pack, null, 2));
+            return console.log(chalk.green(`\n✔ Legacy pack created: ${pack.package}.cbspak`));
+        }
+
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        const packName = `${pkg.name}-${pkg.version}.cbsext`;
+        console.log(chalk.yellow(`Bundling professional extension: ${chalk.bold(packName)}...`));
         
-        const packedBlocks = [
-            ...files.map(f => JSON.parse(fs.readFileSync(f, 'utf8'))),
-            ...dirs.map(d => {
-                const meta = JSON.parse(fs.readFileSync(path.join(d, 'metadata.json'), 'utf8'));
-                const indexPath = fs.existsSync(path.join(d, 'index.ts')) ? path.join(d, 'index.ts') : path.join(d, 'index.js');
-                let logic = fs.readFileSync(indexPath, 'utf8');
-                if (logic.includes('export function run')) logic = logic.replace('export function run', 'function run');
-                meta.logic = logic;
-                return meta;
-            })
-        ];
-
-        const pack = {
-            package: path.basename(process.cwd()),
-            version: "1.0.0",
-            blocks: packedBlocks
-        };
-        const packName = `${pack.package}.cbspak`;
-        fs.writeFileSync(packName, JSON.stringify(pack, null, 2));
-        console.log(chalk.green(`\n✔ Packed ${packedBlocks.length} blocks into ${chalk.bold(packName)}`));
+        try {
+            // Use tar to create a ZIP (Cross-platform)
+            // -a (auto-compress based on extension), -c (create), -f (file)
+            // We include everything except node_modules (build command already bundled what's needed)
+            execSync(`tar -a -c -f ${packName} --exclude=node_modules .`);
+            console.log(chalk.green(`\n✔ Extension packed successfully: ${chalk.bold(packName)}`));
+            console.log(chalk.dim(`This file is ready for Marketplace installation.`));
+        } catch (e) {
+            console.error(chalk.red(`\n✘ Packing failed: ${e.message}`));
+        }
 
     } else if (command === 'doc' && target) {
         if (!fs.existsSync(target)) return console.error(chalk.red(`Error: File ${target} not found.`));
@@ -215,6 +229,17 @@ async function main() {
             console.error(chalk.red(`\n✘ Test Failed: ${e.message}`));
         }
 
+    } else if (command === 'tutorial') {
+        const tutorialPath = path.join(process.cwd(), 'tutorial.html');
+        if (fs.existsSync(tutorialPath)) {
+            console.log(chalk.cyan(`Opening Developer Guide...`));
+            const start = process.platform === 'win32' ? 'start' : process.platform === 'darwin' ? 'open' : 'xdg-open';
+            exec(`${start} ${tutorialPath}`);
+        } else {
+            console.error(chalk.red(`Error: tutorial.html not found in current directory.`));
+            console.log(chalk.dim(`Try running 'cbs-block create' to generate a project with a tutorial.`));
+        }
+
     } else if (command === 'publish' && target) {
         if (!fs.existsSync(target)) return console.error(chalk.red(`Error: File ${target} not found.`));
         const block = JSON.parse(fs.readFileSync(target, 'utf8'));
@@ -293,13 +318,14 @@ async function main() {
         console.log(chalk.white(`Available commands:`));
         console.log(`  ${chalk.bold('create [name]')}  - Create a new block (file or directory)`);
         console.log(`  ${chalk.bold('build [dir]')}   - Build a directory block into a .cbsblock`);
-        console.log(`  ${chalk.bold('pack')}           - Bundle all blocks in folder into .cbspak`);
+        console.log(`  ${chalk.bold('pack')}           - Bundle workspace into professional .cbsext`);
         console.log(`  ${chalk.bold('init [name]')}    - Initialize a new block project`);
         console.log(`  ${chalk.bold('test <file>')}     - Run unit tests on a block`);
         console.log(`  ${chalk.bold('dev <file>')}      - Watch for changes and re-test`);
         console.log(`  ${chalk.bold('search <query>')} - Search Marketplace from CLI`);
         console.log(`  ${chalk.bold('bench <file>')}    - Benchmark block performance`);
         console.log(`  ${chalk.bold('site')}           - Generate documentation website`);
+        console.log(`  ${chalk.bold('tutorial')}       - Open integrated developer guide`);
         console.log(`  ${chalk.bold('publish <file>')}  - Publish block to CodeBlock Marketplace`);
         console.log(`  ${chalk.bold('version --bump')}  - Bump patch version of package`);
         console.log(`  ${chalk.bold('doc <file>')}     - Generate markdown documentation`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cbs-block",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "SDK for creating CodeBlock Studio blocks",
   "main": "index.js",
   "bin": {

package/templates/README.md

@@ -0,0 +1,18 @@
+# {BLOCK_NAME} Extension
+
+This is a professional CodeBlock Studio block extension.
+
+## Usage
+1.  Customize the logic in `index.js`.
+2.  Update block metadata in `metadata.json`.
+3.  Build the block: `cbs-block build`.
+4.  Test the block: `cbs-block test`.
+
+## Components
+- `index.js`: The execution logic for your block.
+- `metadata.json`: Defines the block's UI (color, ports, category).
+- `package.json`: NPM manifest for dependencies.
+- `tutorial.html`: Integrated developer guide.
+
+## Publishing
+When ready, run `cbs-block publish` to share your block on the CodeBlock Marketplace.

package/templates/tutorial.html

@@ -0,0 +1,54 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Developer Guide - {BLOCK_NAME}</title>
+    <link href="https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;600;800&family=JetBrains+Mono:wght@400;700&display=swap" rel="stylesheet">
+    <style>
+        :root { --primary: #4caf50; --accent: #1ed760; --bg: #0a0a0c; }
+        body { background: var(--bg); color: #e0e0e0; font-family: 'Outfit', sans-serif; line-height: 1.6; margin: 0; }
+        .container { max-width: 800px; margin: 4rem auto; padding: 0 2rem; }
+        .glass { background: rgba(255, 255, 255, 0.03); border: 1px solid rgba(255, 255, 255, 0.08); border-radius: 24px; padding: 2rem; box-shadow: 0 20px 40px rgba(0,0,0,0.4); }
+        h1 { font-size: 2.5rem; background: linear-gradient(45deg, var(--primary), var(--accent)); -webkit-background-clip: text; -webkit-text-fill-color: transparent; margin-bottom: 0.5rem; }
+        .badge { display: inline-block; padding: 0.2rem 0.6rem; border-radius: 6px; background: var(--primary); color: #000; font-weight: 800; font-size: 0.7rem; text-transform: uppercase; margin-bottom: 2rem; }
+        pre { background: #000; padding: 1.2rem; border-radius: 12px; border: 1px solid rgba(255,255,255,0.1); overflow-x: auto; font-family: 'JetBrains Mono', monospace; font-size: 0.9rem; }
+        code { color: var(--accent); }
+        .step { margin-bottom: 2rem; }
+        .tip { padding: 1rem; background: rgba(76, 175, 80, 0.1); border-radius: 12px; border-left: 4px solid var(--primary); margin: 1rem 0; }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="glass">
+            <div class="badge">Developer Guide</div>
+            <h1>Building {BLOCK_NAME}</h1>
+            <p>Welcome to your new CodeBlock Studio extension! This guide will help you build and test your block logic.</p>
+
+            <div class="step">
+                <h2>1. Writing Logic</h2>
+                <p>Open <code>index.js</code> and edit the <code>run</code> function. This function receives data from your block's input ports.</p>
+                <pre><code>function run(inputs) {
+  // Your logic here
+  return inputs.input1; 
+}</code></pre>
+            </div>
+
+            <div class="step">
+                <h2>2. Building & Testing</h2>
+                <p>Run these commands in your terminal to see your changes in action:</p>
+                <pre><code>cbs-block build
+cbs-block test myblock.cbsblock</code></pre>
+            </div>
+
+            <div class="tip">
+                <strong>💡 PRO TIP:</strong> You can run <code>npm install <package></code> in this folder and use external libraries in your block logic!
+            </div>
+
+            <footer style="margin-top: 4rem; opacity: 0.4; font-size: 0.8rem; text-align: center;">
+                &copy; 2026 CodeBlock Studio SDK. Created with passion.
+            </footer>
+        </div>
+    </div>
+</body>
+</html>