@devaloop/devalang 0.0.1-alpha.16-hotfix.3 → 0.0.1-alpha.17

package/.cargo/config.toml

@@ -0,0 +1,2 @@
+[target.wasm32-unknown-unknown]
+rustflags = ["--cfg", "getrandom_backend=\"wasm_js\""]

package/.devalang

@@ -1,10 +1,6 @@
-[defaults]
-entry = "./examples"
-output = "./output"
-watch = false
-debug = true
-compress = true
-
-[[banks]]
-path = "devalang://bank/devaloop.808"
-version = "0.0.2"
+[defaults]
+entry = "./examples"
+output = "./output"
+watch = false
+debug = true
+compress = true

package/.github/workflows/ci.yml

@@ -85,7 +85,6 @@ jobs:
   release:
     name: Create GitHub Release
     runs-on: ubuntu-latest
-    if: startsWith(github.ref, 'refs/tags/')
     needs: build
     steps:
       - name: Download all build artifacts

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "devalang"
-version = "0.0.1-alpha.16-hotfix.3"
+version = "0.0.1-alpha.17"
 authors = ["Devaloop <contact@devaloop.com>"]
 description = "Write music like code. Devalang is a domain-specific language (DSL) for sound designers and music hackers. Compose, automate, and control sound — in plain text."
 license = "MIT"
@@ -30,6 +30,7 @@ default = ["cli"]
 cli = ["crossterm", "indicatif", "inquire", "zip", "reqwest", "flate2", "tokio"]
 
 [dependencies]
+devalang_types = { path = "rust/types" }
 clap = { version = "4.5", features = ["derive"] }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
@@ -47,6 +48,7 @@ crossterm =  { version = "0.27", optional = true }
 indicatif = { version = "0.17", optional = true }
 inquire = { version = "0.7.5", optional = true }
 js-sys = "0.3"
+getrandom = { version = "0.3", features = ["wasm_js"] }
 reqwest = { version = "0.12.22", optional = true, features = ["json"] }
 flate2 = { version = "1.0", optional = true }
 tokio = { version = "1", features = ["full"], optional = true }
@@ -57,4 +59,18 @@ tiny_http = "0.9.0"
 dirs = "5"
 urlencoding = "2.1"
 uuid = { version = "1.18.0", features = ["v4"] }
-wasmtime = "19"
+console_error_panic_hook = "0.1.7"
+
+# For wasm32, enable wasm-friendly randomness backends and avoid
+# pulling in native-only CLI dependencies.
+[target.'cfg(target_arch = "wasm32")'.dependencies]
+getrandom = { version = "0.3", features = ["wasm_js"] }
+uuid = { version = "1.18.0", features = ["v4", "js", "rng-getrandom"] }
+# Keep a lightweight linkage to the utils crate for wasm builds without
+# enabling native CLI features.
+devalang_utils = { path = "rust/utils", default-features = false }
+
+# devalang_utils with CLI and wasmtime are only needed for native targets.
+[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
+devalang_utils = { path = "rust/utils", features = ["cli"] }
+wasmtime = "19"

package/README.md

@@ -28,13 +28,13 @@ Whether you're building a track, shaping textures, or performing live, Devalang
 
 From studio sketches to live sets, Devalang gives you rhythmic control — with the elegance of code.
 
-> 🚧 Alpha Notice 🚧
+> **🚧 Notice 🚧**
 >
-> Includes synthesis, playback, and rendering features, but is still in early development.
+> Includes synthesis, playback, and rendering features, but is still in early development, and breaking changes may occur.
 >
-> NEW: [Devaforge is now available for creating addons](https://github.com/devaloop-labs/devaforge).
+> **NEW**: [Devaforge is now available for creating addons](https://github.com/devaloop-labs/devaforge).
 >
-> NEW: Devalang is now available for **Windows**, **Linux**, and **macOS**.
+> **NEW**: Now available for Windows, Linux, and macOS.
 
 ## 📚 Quick Access
 
@@ -52,24 +52,47 @@ From studio sketches to live sets, Devalang gives you rhythmic control — with
 
 ### Try Devalang in your browser
 
-> Have a look at the [Playground](https://playground.devalang.com) to try Devalang directly in your browser
+> [Have a look at the Playground to try Devalang directly in your browser](https://playground.devalang.com)
 
-### Try Devalang CLI
+### Try Devalang in your terminal
+
+#### With Node.js
 
 ```bash
-# Install Devalang CLI globally
 npm install -g @devaloop/devalang@latest
+```
+
+#### With Rust
+
+```bash
+cargo install devalang
+```
 
-# Create a new Devalang project
+#### Initialize a new project
+
+```bash
 devalang init --name my-project --template minimal
 ```
 
+#### Write your first script
+
 Create a new Devalang file `src/index.deva` in the project directory:
 
 ```deva
 # src/index.deva
 
+# BPM definition
+bpm 125
+
+# Bank picking (make sure you installed it)
+bank devaloop.808 as my808Bank
+
 group myGroup:
+    # Rhythmic (each beat playing a kick)
+    on beat:
+        .my808Bank.kick 1/4
+
+    # Synth definition with ADSR
     let myLead = synth sine {
         attack: 0,
         decay: 100,
@@ -77,12 +100,27 @@ group myGroup:
         release: 100
     }
 
+    # Global automation
     automate myLead:
+        param volume {
+            0% = 0.0
+            100% = 0.5
+        }
         param pitch {
             0% = -12.0
             100% = 12.0
         }
 
+    # Notes in a loop with condition
+    for i in [1, 2, 3]:
+        if i == 3:
+            myLead -> note(C5, { duration: 200 })
+            print "Playing note C5 for " + i
+
+    # Pause runtime for 500ms
+    sleep 500
+
+    # Note with automation
     myLead -> note(C4, {
         duration: 400,
         velocity: 0.8,
@@ -94,27 +132,26 @@ group myGroup:
         }
     })
 
+    # Notes with params
     myLead -> note(E4, { duration: 400 })
     myLead -> note(G4, { duration: 600, glide: true, target_freq: 659.25 })
     myLead -> note(B3, { duration: 400, slide: true, target_amp: 0.3 })
 
-    for i in [1, 2, 3]:
-        myLead -> note(C5, { duration: 200 })
-        print "Playing note C5 for " + i
-
+# Calling the group to play it
 call myGroup
 ```
 
 ### And the best part ? You can play it directly from the command line:
 
+#### Play the script once
+
 ```bash
-# Play the Devalang file
 devalang play
+```
 
-# Play the Devalang file with watch mode
-devalang play --watch
+#### **LIVE mode** (repeat the playback + watch mode)
 
-# LIVE mode (repeat the playback + watch mode)
+```bash
 devalang play --repeat
 ```
 
@@ -124,7 +161,7 @@ devalang play --repeat
 
 ## ❓ Why Devalang ?
 
-- 🎹 Prototype audio ideas without opening a DAW, even VSCode
+- 🎹 Prototype audio ideas without opening a DAW, even VSCode with our Playground
 - 💻 Integrate sound into code-based workflows
 - 🎛️ Control audio parameters through readable syntax
 - 🧪 Build musical logic with variables and conditions
@@ -132,31 +169,39 @@ devalang play --repeat
 
 ## 🚀 Features
 
-- 🎵 **Audio Engine**: Integrated audio playback and rendering
-- 🧩 **Module system** for importing and exporting variables between files
-- 📦 **Addon manager** for managing external banks, plugins and more
-- 📜 **Structured AST** generation for debugging and future compilation
-- 🔢 **Basic data types**: strings, numbers, booleans, maps, arrays
-- 👁️ **Watch mode** for `build`, `check` and `play` commands
-- 📂 **Project templates** for quick setup
-- 🎛️ **Custom samples**: easily load and trigger your own audio files
-- 🔄 **Looping and grouping**: create complex patterns with ease
+- ⚡ **Fast Build & Hot Reload** — optimized build process for quicker iteration.
+- 🎵 **Audio Engine & Real-time runner** — low-latency playback, render-to-file, and a realtime runner used by `devalang play` for live feedback.
+- ▶️ **Live mode (watch + repeat)** — edit and hear changes instantly with `devalang play --repeat` and watch mode.
+- 🧩 **Language primitives** — synths, notes, ADSR, maps, arrays, loops, conditionals and functions for expressive musical logic.
+- 🎛️ **Per-note automation & modulators** — `automate` maps, `$mod.*`, `$easing.*` and `$math.*` helpers for envelopes and LFOs.
+- 🧩 **Module system & structured AST** — import/export variables, stable AST output for debugging and tooling.
+- 🧰 **Plugins & Addons (WASM-ready)** — install plugins/banks, `@use` directive, and WASM plugin integration so plugins can render or process audio at runtime.
+- 📦 **Addon manager & Devaforge** — CLI commands to discover/install banks, plugins and templates; `devaforge` helps create addons.
+- ⚙️ **CLI tooling** — `build`, `check`, `play`, `install`, `init`, `discover`, `telemetry` and more with consistent flags (`--watch`, `--debug`, `--compress`).
+- 📂 **Project templates & examples** — quick-start templates and many example projects in `examples/`.
+- 🧑‍💻 **TypeScript API & WASM distribution** — Node-friendly package with TypeScript bindings and a WASM build for browser/Node usage.
+- 🧰 **Editor & formatting support** — VSCode extension and Prettier plugin to edit Devalang with syntax and formatting support.
+- 🎵 **Custom samples & banks** — drop samples into `.deva` and reference them from code; banks of sounds for fast composition.
+- 🔄 **Looping, grouping & scheduling** — precise beat-tied scheduling primitives for complex rhythmic patterns.
 
 ## 📄 Documentation
 
-### Please refer to the [online documentation](https://docs.devalang.com) for detailed information on syntax, features, and usage examples
+### [Please refer to the online documentation](https://docs.devalang.com) for detailed information on syntax, features, and usage examples
 
-## 🧯 Known issues
+## 📰 What's new
 
-- No smart modules yet, all groups, variables, and samples must be explicitly imported where used
-- No support yet for cross-platform builds (Linux, macOS)
+- **Devaforge**: Introduced a new system for creating and managing addons, including a CLI for addon generation.
+- **Documentation updates**: Improved documentation for clarity and completeness.
+- **Discovering addons**: Introduced a new command to detect addons.
+- **Public TypeScript API**: Added a public TypeScript API for easier integration.
+- **Improved error messages**: Enhanced error messages for better debugging.
+- **Bug fixes**: Various bug fixes and stability improvements.
 
 ## 🧪 Roadmap Highlights
 
 For more info, see [docs/ROADMAP.md](./docs/ROADMAP.md)
 
-- ⏳ Other statements (e.g `pattern`, ...)
-- ⏳ Addon generator
+- ⏳ Smart modules
 
 ## 🛡️ License
 

package/docs/CHANGELOG.md

@@ -4,6 +4,52 @@
 
 # Changelog
 
+## Version 0.0.1-alpha.17 (2025-08-31)
+
+### ✨ Addons
+
+- Discovering addons: use the CLI to discover plugins or banks : place compiled addons (.devabank, .devaplugin) anywhere into your `.deva` folder, then run:
+
+  ```bash
+  devalang discover
+  ```
+
+- Installing external addons: use the CLI to install addons:
+
+  ```bash
+  devalang install <plugin | bank> user.myPlugin
+  ```
+
+- Plugin usage: you can now reference installed plugins directly from Devalang source
+  using the `@use` directive and an optional alias. Examples:
+
+  - `@use user.myPlugin` — exposes the plugin under its default name
+  - `@use user.myPlugin as myAlias` — expose the plugin as `myAlias` for shorter calls
+
+### 🧩 Packaging & TypeScript
+
+- Improved packaging and postinstall logic for the TypeScript/WASM distribution; the
+  Node package now avoids hard-failing when optional native binaries are not available.
+- `out-tsc` postinstall now performs guarded downloads and better logging to help consumers diagnose installation issues on CI or constrained environments.
+
+### 🧠 Architecture & Refactor
+
+- Introduced a shared `devalang_types` crate to centralize project types and config structures — this simplifies cross-crate typing between the CLI, core, utils and WASM artifacts.
+- Split utilities into a reusable `devalang_utils` crate (logger, watcher, spinner, file helpers, telemetry) and moved several helpers (path resolution, file copying, safe archive extraction) to that crate.
+- Modularized CLI features, clean separation between build/process, realtime runner, IO helpers and stats collection.
+
+### 🐛 Bug fixes & stability
+
+- Multiple robustness fixes across the parser, preprocessor and audio engine:
+  - dotted identifiers and synth/provider resolution improvements,
+  - safer path resolution for `.deva` resources (banks, plugins, presets),
+  - improved error collection and logging with annotated stacks for better debug output.
+- Audio runtime: better BPM/duration estimation and loop handling in the realtime runner to avoid premature termination of periodic handlers while loops execute.
+
+### 🧪 Tests & CI
+
+- Added test scaffolding and types to centralize cross-crate tests (test harness and lightweight types prepared in `devalang_types`); this enables adding unit tests incrementally without duplicating type definitions. (Full test coverage is ongoing.)
+
 ## Version 0.0.1-alpha.16-hotfix.2 (2025-08-29)
 
 ### 🌎 Ecosystem

package/docs/ROADMAP.md

@@ -22,10 +22,13 @@ Devalang is a work in progress. Here’s what we’re planning next:
 - ✅ **Sample loading**: Add `@load` assignment to load samples (.mp3, .wav) for use as values.
 - ✅ **WASM support**: Compile Devalang to WebAssembly for use in web applications and other environments.
 - ✅ **VSCode extension**: Create a VSCode extension for syntax highlighting and code completion.
-- ✅ **Addon generator**: Implement addon generation for creating reusable plugins, banks and presets.
 
-## Upcoming
+## In Progress
+
+- ⏳ **Addon generator**: Implement addon generation for creating reusable plugins, banks and presets.
+- ⏳ **Testing**: Expand test coverage for all features.
+
+## Planned
 
 - ⏳ **Smart modules**: Let Devalang detect and use groups, samples, and variables without needing to import them manually.
-- ⏳ **Other statements**: Implement `pattern`, and other control structures.
-- ⏳ **Testing**: Expand test coverage for all features.
+- ⏳ **Other statements**: Implement `pattern`, and other control structures.

package/examples/index.deva

@@ -1,43 +1,60 @@
-# This file demonstrates general uses of Devalang.
+# This file demonstrates general use cases of Devalang.
 
-bpm 120
+# BPM definition
+bpm 125
 
-group main:
-	let lead = synth sine {
+# Bank picking (make sure you have installed it)
+bank devaloop.808 as my808Bank
+
+group myGroup:
+    # Rhythmic (each beat playing a kick)
+    on beat:
+        .my808Bank.kick 1/4
+
+    # Synth definition with ADSR
+    let myLead = synth sine {
         attack: 0,
         decay: 100,
         sustain: 100,
         release: 100
     }
 
-	# Global automation for this synth (applies to subsequent notes)
-	automate lead:
-		param volume {
-			0% = 0.0
-			100% = 1.0
-		}
-		param pan {
-			0% = -1.0
-			100% = 1.0
-		}
-		param pitch {
-			0% = -12.0
-			100% = 12.0
-		}
-
-	# Notes (per-note automation can override globals)
-	lead -> note(C4, {
-		duration: 400,
-		velocity: 0.8,
-		automate: {
-			pan: {
-				0%: -1.0
-				100%: 0.0
-			}
-		}
-	})
-	lead -> note(E4, { duration: 400 })
-	lead -> note(G4, { duration: 600, glide: true, target_freq: 659.25 })
-	lead -> note(B3, { duration: 400, slide: true, target_amp: 0.3 })
-
-call main
+    # Global automation
+    automate myLead:
+        param volume {
+            0% = 0.0
+            100% = 0.5
+        }
+        param pitch {
+            0% = -12.0
+            100% = 12.0
+        }
+
+    # Notes in a loop with condition
+    for i in [1, 2, 3]:
+        if i == 3:
+            myLead -> note(C5, { duration: 200 })
+            print "Playing note C5 for " + i
+
+    # Pause runtime for 500ms
+    sleep 500
+
+    # Note with automation
+    myLead -> note(C4, {
+        duration: 400,
+        velocity: 0.8,
+        automate: {
+            pan: {
+                0%: -1.0,
+                100%: 0.0
+            }
+        }
+    })
+
+    # Notes with params
+    myLead -> note(E4, { duration: 400 })
+    myLead -> note(G4, { duration: 600, glide: true, target_freq: 659.25 })
+    myLead -> note(B3, { duration: 400, slide: true, target_amp: 0.3 })
+
+# Calling the group to play it
+call myGroup

package/out-tsc/bin/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/out-tsc/core/functions/index.d.ts

@@ -0,0 +1,37 @@
+import { ParseResult } from "../types/result";
+import { DebugResult } from "../types/result";
+/**
+ * Parses the user code.
+ * @param entry_path The entry path for the code.
+ * @param source The source code to parse.
+ * @returns ParseResult | any
+ */
+export declare function parse(entry_path: string, source: string): ParseResult | any;
+/**
+ * Renders the debug information for the user code.
+ * @param user_code The user-provided code to render debug information for.
+ * @returns DebugResult | any
+ */
+export declare function debug_render(user_code: string): DebugResult | any;
+/**
+ * Renders audio from the user code.
+ * @param user_code The user-provided code to render audio from.
+ * @returns Float32Array
+ */
+export declare function render_audio(user_code: string): Float32Array;
+/**
+ * Register a JS callback to receive playhead events { time, line, column } during playback.
+ * The callback will be called with a single object argument.
+ * @param cb The callback function to register.
+ * @returns void
+ */
+export declare function register_playhead_callback(cb: (ev: {
+    time: number;
+    line: number;
+    column: number;
+}) => void): any;
+/**
+ * Unregisters the JS callback for playhead events.
+ * @returns void
+ */
+export declare function unregister_playhead_callback(): any;

package/out-tsc/core/functions/index.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parse = parse;
+exports.debug_render = debug_render;
+exports.render_audio = render_audio;
+exports.register_playhead_callback = register_playhead_callback;
+exports.unregister_playhead_callback = unregister_playhead_callback;
+let wasmPkg = undefined;
+try {
+    // prefer runtime pkg generated by wasm-pack when available
+    // require at runtime so the package can be used even if wasm hasn't been built
+    // (this keeps tests and consumers robust).
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    wasmPkg = require("../../pkg/devalang_core");
+}
+catch (_e) {
+    wasmPkg = undefined;
+}
+/**
+ * Parses the user code.
+ * @param entry_path The entry path for the code.
+ * @param source The source code to parse.
+ * @returns ParseResult | any
+ */
+function parse(entry_path, source) {
+    if (wasmPkg && typeof wasmPkg.parse === "function") {
+        return wasmPkg.parse(entry_path, source);
+    }
+    throw new Error("WASM binding 'parse' not available. Build the wasm package or use the JS runtime.");
+}
+/**
+ * Renders the debug information for the user code.
+ * @param user_code The user-provided code to render debug information for.
+ * @returns DebugResult | any
+ */
+function debug_render(user_code) {
+    if (wasmPkg && typeof wasmPkg.debug_render === "function") {
+        return wasmPkg.debug_render(user_code);
+    }
+    throw new Error("WASM binding 'debug_render' not available. Build the wasm package or use the JS runtime.");
+}
+/**
+ * Renders audio from the user code.
+ * @param user_code The user-provided code to render audio from.
+ * @returns Float32Array
+ */
+function render_audio(user_code) {
+    if (wasmPkg && typeof wasmPkg.render_audio === "function") {
+        return wasmPkg.render_audio(user_code);
+    }
+    // Fallback: indicate missing wasm with an empty buffer rather than breaking consumers.
+    return new Float32Array(0);
+}
+/**
+ * Register a JS callback to receive playhead events { time, line, column } during playback.
+ * The callback will be called with a single object argument.
+ * @param cb The callback function to register.
+ * @returns void
+ */
+function register_playhead_callback(cb) {
+    if (wasmPkg && typeof wasmPkg.register_playhead_callback === "function") {
+        return wasmPkg.register_playhead_callback(cb);
+    }
+    // no-op fallback
+    return;
+}
+/**
+ * Unregisters the JS callback for playhead events.
+ * @returns void
+ */
+function unregister_playhead_callback() {
+    if (wasmPkg && typeof wasmPkg.unregister_playhead_callback === "function") {
+        return wasmPkg.unregister_playhead_callback();
+    }
+    return;
+}

package/out-tsc/core/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Core functionality for the Devalang language.
+ * This module exports all the core types and functions used in the language.
+ */
+export * from "./types/index";
+export * from "./functions/index";

package/out-tsc/core/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Core functionality for the Devalang language.
+ * This module exports all the core types and functions used in the language.
+ */
+__exportStar(require("./types/index"), exports);
+__exportStar(require("./functions/index"), exports);

package/out-tsc/core/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./result";
+export * from "./statement";
+export * from "./value";
+export * from "./plugin";

package/out-tsc/core/types/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./result"), exports);
+__exportStar(require("./statement"), exports);
+__exportStar(require("./value"), exports);
+__exportStar(require("./plugin"), exports);

package/out-tsc/core/types/plugin.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Represents a plugin export.
+ */
+export interface PluginExport {
+    name: string;
+    kind: string;
+    default?: any;
+}
+/**
+ * Represents a plugin.
+ */
+export interface PluginInfo {
+    author: string;
+    name: string;
+    version?: string;
+    description?: string;
+    exports: PluginExport[];
+}

package/out-tsc/core/types/plugin.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/out-tsc/core/types/result.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Represents an error that occurred during parsing.
+ */
+export interface ErrorResult {
+    message: string;
+    line: number;
+    column: number;
+}
+/**
+ * Represents the result of parsing user code.
+ */
+export interface ParseResult {
+    ok: boolean;
+    ast: string;
+    errors: ErrorResult[];
+}
+/**
+ * Represents the result of debugging user code.
+ */
+export interface DebugResult {
+    samples_len: number;
+    any_nonzero: boolean;
+    ast: string;
+    note_count: number;
+    global_vars: string[];
+    statements_count: number;
+}