moonscratch 0.1.0-alpha.0

package/.agents/skills/moonbit-practice/reference/configuration.md

@@ -0,0 +1,228 @@
+---
+title: 'MoonBit Configuration Reference'
+---
+
+# MoonBit Configuration Reference
+
+## File Structure
+
+```
+my-project/
+├── moon.mod.json    # Module configuration (project-wide)
+└── src/
+    ├── moon.pkg       # Package configuration (new format)
+    └── main.mbt
+```
+
+## Migrating from moon.pkg.json to moon.pkg
+
+`moon.pkg.json` is being migrated to the custom syntax `moon.pkg`. Convert with:
+
+```bash
+NEW_MOON_PKG=1 moon fmt
+```
+
+This converts `moon.pkg.json` to `moon.pkg`.
+
+## moon.pkg (New Format)
+
+Compared to JSON: supports comments, trailing commas, and more concise syntax.
+
+### Imports
+
+```moonbit
+// Basic import
+import {
+  "moonbitlang/async/io",
+  "path/to/pkg" as @alias,
+}
+
+// Test imports
+import "test" {
+  "path/to/pkg5",
+}
+
+// White-box test imports
+import "wbtest" {
+  "path/to/pkg7",
+}
+```
+
+### Options
+
+```moonbit
+options(
+  "is-main": true,
+  "bin-name": "name",
+  link: { "native": { "cc": "gcc" } },
+)
+```
+
+### Comparison with JSON
+
+| Feature        | JSON Format      | moon.pkg Format |
+| -------------- | ---------------- | --------------- |
+| Comments       | ❌ Not supported | ✅ Supported    |
+| Trailing comma | ❌ Not supported | ✅ Supported    |
+| Readability    | Low (verbose)    | High (concise)  |
+
+## moon.mod.json (Module Configuration)
+
+### Required Fields
+
+```json
+{
+  "name": "username/project-name",
+  "version": "0.1.0"
+}
+```
+
+### Dependencies
+
+```json
+{
+  "deps": {
+    "moonbitlang/x": "0.4.6",
+    "username/other": { "path": "../other" }
+  }
+}
+```
+
+### Metadata
+
+```json
+{
+  "license": "MIT",
+  "repository": "https://github.com/...",
+  "description": "...",
+  "keywords": ["example", "test"]
+}
+```
+
+### Source Directory
+
+```json
+{
+  "source": "src"
+}
+```
+
+### Target Specification
+
+```json
+{
+  "preferred-target": "js"
+}
+```
+
+### Warning Configuration
+
+```json
+{
+  "warn-list": "-2-4",
+  "alert-list": "-alert_1"
+}
+```
+
+## moon.pkg.json (Package Configuration)
+
+### Main Package
+
+```json
+{
+  "is-main": true
+}
+```
+
+### Dependencies
+
+```json
+{
+  "import": [
+    "moonbitlang/quickcheck",
+    { "path": "moonbitlang/x/encoding", "alias": "lib" }
+  ],
+  "test-import": [...],
+  "wbtest-import": [...]
+}
+```
+
+### Conditional Compilation
+
+```json
+{
+  "targets": {
+    "only_js.mbt": ["js"],
+    "only_wasm.mbt": ["wasm"],
+    "not_js.mbt": ["not", "js"],
+    "debug_only.mbt": ["debug"],
+    "js_release.mbt": ["and", ["js"], ["release"]]
+  }
+}
+```
+
+Conditions: `wasm`, `wasm-gc`, `js`, `debug`, `release`
+Operators: `and`, `or`, `not`
+
+### Link Options
+
+#### JS Backend
+
+```json
+{
+  "link": {
+    "js": {
+      "exports": ["hello", "foo:bar"],
+      "format": "esm"
+    }
+  }
+}
+```
+
+format: `esm` (default), `cjs`, `iife`
+
+#### Wasm Backend
+
+```json
+{
+  "link": {
+    "wasm-gc": {
+      "exports": ["hello"],
+      "use-js-builtin-string": true
+    }
+  }
+}
+```
+
+### Pre-build
+
+```json
+{
+  "pre-build": [
+    {
+      "input": "a.txt",
+      "output": "a.mbt",
+      "command": ":embed -i $input -o $output"
+    }
+  ]
+}
+```
+
+`:embed` converts files to MoonBit source (`--text` or `--binary`)
+
+## Warning Numbers
+
+Common ones:
+
+- `1` Unused function
+- `2` Unused variable
+- `11` Partial pattern matching
+- `12` Unreachable code
+- `27` Deprecated syntax
+
+Check all: `moonc build-package -warn-help`
+
+## References
+
+- Module: https://docs.moonbitlang.com/en/stable/toolchain/moon/module
+- Package: https://docs.moonbitlang.com/en/stable/toolchain/moon/package

package/.agents/skills/moonbit-practice/reference/ffi.md

@@ -0,0 +1,229 @@
+---
+title: 'MoonBit FFI Reference'
+---
+
+# MoonBit FFI Reference
+
+## External Type Declaration
+
+```moonbit
+#external
+type ExternalRef
+```
+
+- Wasm: `externref`
+- JS: `any`
+- C: `void*`
+
+## External Function Declaration
+
+### JavaScript Backend
+
+```moonbit
+///| Module.function format
+fn cos(d : Double) -> Double = "Math" "cos"
+
+///| Inline JavaScript
+extern "js" fn cos(d : Double) -> Double =
+  #|(d) => Math.cos(d)
+
+///| Multi-line
+extern "js" fn fetch_json(url : String) -> Value =
+  #|(url) => fetch(url).then(r => r.json())
+```
+
+### Wasm Backend
+
+```moonbit
+///| Import from host
+fn cos(d : Double) -> Double = "math" "cos"
+
+///| Inline Wasm
+extern "wasm" fn identity(d : Double) -> Double =
+  #|(func (param f64) (result f64))
+```
+
+### C Backend
+
+```moonbit
+extern "C" fn put_char(ch : UInt) = "putchar"
+```
+
+## Type Mapping
+
+### JavaScript
+
+| MoonBit          | JavaScript   |
+| ---------------- | ------------ |
+| `String`         | `string`     |
+| `Bool`           | `boolean`    |
+| `Int`, `Double`  | `number`     |
+| `BigInt`         | `bigint`     |
+| `Bytes`          | `Uint8Array` |
+| `Array[T]`       | `T[]`        |
+| `#external type` | `any`        |
+
+### Wasm
+
+| MoonBit          | Wasm        |
+| ---------------- | ----------- |
+| `Bool`, `Int`    | `i32`       |
+| `Int64`          | `i64`       |
+| `Float`          | `f32`       |
+| `Double`         | `f64`       |
+| `#external type` | `externref` |
+
+## JavaScript FFI Patterns
+
+### Handling undefined/null
+
+```moonbit
+#external
+pub type Value
+
+extern "js" fn Value::undefined() -> Value = "() => undefined"
+extern "js" fn Value::null() -> Value = "() => null"
+extern "js" fn Value::is_undefined(self : Value) -> Bool =
+  #|(n) => Object.is(n, undefined)
+```
+
+### Type Cast (%identity)
+
+```moonbit
+fn[T] Value::cast_from(value : T) -> Value = "%identity"
+fn[T] Value::cast(self : Value) -> T = "%identity"
+```
+
+### Error Handling
+
+```moonbit
+extern "js" fn wrap_ffi(
+  op : () -> Value,
+  on_ok : (Value) -> Unit,
+  on_error : (Value) -> Unit,
+) -> Unit =
+  #|(op, on_ok, on_error) => {
+  #|  try { on_ok(op()); }
+  #|  catch (e) { on_error(e); }
+  #|}
+```
+
+### Loading Node.js Modules
+
+```moonbit
+extern "js" fn require_ffi(path : String) -> Value =
+  #|(path) => require(path)
+
+// Usage
+let path_module = require_ffi("node:path")
+```
+
+### ESM Import with #module (Recommended)
+
+The `#module` attribute generates ESM `import` statements in the output JavaScript.
+
+```moonbit
+#module("node:fs")
+extern "js" fn readFileSync(path : String, encoding : String) -> String = "readFileSync"
+
+#module("node:path")
+extern "js" fn basename(path : String) -> String = "basename"
+extern "js" fn dirname(path : String) -> String = "dirname"
+```
+
+This generates:
+
+```javascript
+import { readFileSync } from 'node:fs'
+import { basename, dirname } from 'node:path'
+```
+
+#### Default Export
+
+Use `default` as the function name to import the default export:
+
+```moonbit
+#module("lodash")
+extern "js" fn lodash() -> Value = "default"
+```
+
+Generates:
+
+```javascript
+import lodash from 'lodash'
+```
+
+#### npm Packages
+
+Works with any npm package:
+
+```moonbit
+#module("zod")
+extern "js" fn z() -> Value = "z"
+
+#module("marked")
+extern "js" fn marked(input : String) -> String = "marked"
+```
+
+#### Requirements
+
+- Must use `"format": "esm"` in `moon.pkg.json` link config
+- Target must be JavaScript backend (`--target js`)
+
+#### Limitations
+
+- **Only functions can be imported** - classes and objects cannot be directly imported via `#module`
+- To use classes or objects, import them through a wrapper function:
+
+```moonbit
+#module("some-lib")
+extern "js" fn get_some_class() -> Value = "SomeClass"
+
+// Then use it via Value operations
+let cls = get_some_class()
+```
+
+## Exporting Functions
+
+Configure in `moon.pkg.json`:
+
+```json
+{
+  "link": {
+    "js": {
+      "exports": ["add", "fib:fibonacci"],
+      "format": "esm"
+    }
+  }
+}
+```
+
+## Callbacks
+
+### FuncRef (No Closures)
+
+```moonbit
+///| Only functions without free variables
+fn register(callback : FuncRef[() -> Unit]) -> Unit
+```
+
+### Regular Closures
+
+In JavaScript, closures are handled automatically.
+
+## Custom Enum Values
+
+```moonbit
+enum Flags {
+  Read = 1
+  Write = 2
+  ReadWrite = 3
+}
+```
+
+Useful for compatibility with C library flags.
+
+## References
+
+- FFI: https://docs.moonbitlang.com/en/stable/language/ffi
+- JS FFI Guide: https://www.moonbitlang.com/pearls/moonbit-jsffi

package/.agents/skills/moonbit-practice/reference/ide.md

@@ -0,0 +1,189 @@
+---
+title: 'moon ide'
+---
+
+## Code Navigation with `moon ide`
+
+**ALWAYS use `moon ide` for code navigation in MoonBit projects instead of manual file searching, grep, or semantic search.**
+
+This tool provides two essential commands for precise code exploration:
+
+### Core Commands
+
+- `moon ide goto-definition` - Find where a symbol is defined
+- `moon ide find-references` - Find all usages of a symbol
+
+### Query System
+
+Symbol lookup uses a two-part query system for precise results:
+
+#### 1. Symbol Name Query (`-query`)
+
+Fuzzy search for symbol names with package filtering support:
+
+```bash
+# Find any symbol named 'symbol'
+moon ide goto-definition -query 'symbol'
+
+# Find methods of a specific type
+moon ide goto-definition -query 'Type::method'
+
+# Find trait method implementations
+moon ide goto-definition -query 'Trait for Type with method'
+
+# Find symbol in specific package using @pkg prefix
+moon ide goto-definition -query '@moonbitlang/x encode'
+
+# Find symbol in multiple packages (searches in pkg1 OR pkg2)
+moon ide goto-definition -query '@username/mymodule/pkg1 @username/mymodule/pkg2 helper'
+
+# Find symbol in nested package
+moon ide goto-definition -query '@username/mymodule/mypkg helper'
+```
+
+**Supported symbols**: functions, constants, let bindings, types, structs, enums, traits
+
+**Package filtering**: Prefix your query with `@package_name` to scope the search. Multiple `@pkg` prefixes create an OR condition.
+
+#### 2. Tag-based Filtering (`-tags`)
+
+Pre-filter symbols by characteristics before name matching:
+
+**Visibility tags**:
+
+- `pub` - Public symbols
+- `pub all` - Public structs with all public fields
+- `pub open` - Public traits with all methods public
+- `priv` - Private symbols
+
+**Symbol type tags**:
+
+- `type` - Type definitions (struct, enum, typealias, abstract)
+- `error` - Error type definitions
+- `enum` - Enum definitions and variants
+- `struct` - Struct definitions
+- `alias` - Type/function/trait aliases
+- `let` - Top-level let bindings
+- `const` - Constant definitions
+- `fn` - Function definitions
+- `trait` - Trait definitions
+- `impl` - Trait implementations
+- `test` - Named test functions
+
+**Combine tags with logical operators**:
+
+```bash
+# Public functions only
+moon ide goto-definition -tags 'pub fn' -query 'my_func'
+
+# Functions or constants
+moon ide goto-definition -tags 'fn | const' -query 'helper'
+
+# Public functions or constants
+moon ide goto-definition -tags 'pub (fn | const)' -query 'api'
+
+# Public types or traits
+moon ide goto-definition -tags 'pub (type | trait)' -query 'MyType'
+```
+
+### Practical Examples
+
+```bash
+# Find public function definition
+moon ide goto-definition -tags 'pub fn' -query 'maximum'
+
+# Find all references to a struct
+moon ide find-references -tags 'struct' -query 'Rectangle'
+
+# Find trait implementations
+moon ide goto-definition -tags 'impl' -query 'Show for MyType'
+
+# Find errors in specific package
+moon ide goto-definition -tags 'error' -query '@mymodule/parser ParseError'
+
+# Find symbol across multiple packages
+moon ide goto-definition -query '@moonbitlang/x @moonbitlang/core encode'
+
+# Combine package filtering with tags
+moon ide goto-definition -tags 'pub fn' -query '@username/myapp helper'
+```
+
+### Query Processing
+
+The tool processes queries in this order:
+
+1. Filter symbols by `-tags` conditions
+2. Extract package scope from `@pkg` prefixes in `-query`
+3. Fuzzy match remaining symbols by name
+4. Return top 3 best matches with location information
+
+**Best Practice**: Start with `-tags` to reduce noise, then use `@pkg` prefixes in `-query` to scope by package for precise navigation.
+
+## Additional IDE Commands
+
+### `moon ide peek-def`
+
+Display definitions inline. More accurate than grep (semantic search).
+
+```bash
+# Top-level symbol definition
+$ moon ide peek-def String::rev
+Found 1 symbols matching 'String::rev':
+`pub fn String::rev` in package moonbitlang/core/builtin at .../string_methods.mbt:1039-1044
+
+# Local symbol definition with location
+$ moon ide peek-def Parser -loc src/parse.mbt:46:4
+Definition found at file src/parse.mbt
+  | ///|
+2 | priv struct Parser {
+  |             ^^^^^^
+  |   bytes : Bytes
+  |   mut pos : Int
+  | }
+```
+
+### `moon ide outline`
+
+List top-level symbols in a package or file.
+
+```bash
+# Directory (package) outline
+$ moon ide outline .
+spec.mbt:
+ L003 | pub(all) enum CStandard {
+       ...
+ L013 | pub(all) struct Position {
+       ...
+
+# Single file outline
+$ moon ide outline parser.mbt
+```
+
+### `moon ide find-references`
+
+Find all references to a symbol.
+
+```bash
+$ moon ide find-references TranslationUnit
+```
+
+## `moon doc` for API Discovery
+
+**CRITICAL**: `moon doc '<query>'` is the primary tool for API discovery. Faster and more accurate than grep.
+
+```bash
+# Empty query: list available packages
+moon doc ''
+
+# List type methods
+moon doc "String"
+
+# List symbols in a package
+moon doc "@buffer"
+
+# Specific function details
+moon doc "@buffer.new"
+
+# Glob pattern
+moon doc "String::*rev*"
+```