jac-coder 0.1.0__py3-none-any.whl

jac_coder/data/rules/fullstack.md

@@ -0,0 +1,362 @@
+# Fullstack Jac Pitfalls — .cl.jac Frontend + Backend Integration
+
+> These rules apply when building fullstack Jaseci apps with .cl.jac frontend components.
+> Everything in core_jac.md ALSO applies. This file covers the additional fullstack gotchas.
+
+---
+
+## File Types
+
+- `.jac` — Backend code (nodes, endpoints, walkers). Uses Python runtime.
+- `.cl.jac` — Frontend code (React components). Compiles to JavaScript.
+
+---
+
+## BEFORE WRITING ANY CODE
+
+**Read `jac.toml` FIRST.** Only use npm packages listed in `[dependencies.npm]`. Do NOT import unlisted libraries. NEVER assume any UI library is available. Use plain Tailwind CSS + inline SVG for styling and icons.
+
+---
+
+## Backend Rules (.jac)
+
+### 1. ALL backend code goes in `main.jac`
+
+Do NOT split backend into multiple files. Nodes, endpoints, walkers — all in `main.jac`.
+
+### 2. Endpoint types: `def:pub` vs `def:priv` vs `walker:pub`
+
+```jac
+# Public — anyone can call
+def:pub get_items() -> list {
+    return [{"id": str(i.id), "title": i.title} for i in [root-->][?:Item]];
+}
+
+# Private — requires login, per-user isolated root
+def:priv get_my_items() -> list {
+    return [{"id": str(i.id), "title": i.title} for i in [root-->][?:Item]];
+}
+
+# Walker — for complex graph traversal
+walker :pub get_details {
+    has item_id: str;
+    can find with Root entry {
+        for i in [-->][?:Item] {
+            if str(i.id) == self.item_id { visit i; return; }
+        }
+        report {"error": "not found"};
+    }
+}
+```
+
+### 3. Return dicts/lists from endpoints — NOT nodes directly
+
+```jac
+# WRONG — returns node objects
+def:pub get_items() -> list { return [root-->][?:Item]; }
+
+# RIGHT — serialize to dicts
+def:pub get_items() -> list {
+    return [{"id": str(i.id), "title": i.title} for i in [root-->][?:Item]];
+}
+```
+
+### 4. Node CRUD pattern
+
+```jac
+node Item {
+    has title: str;
+    has done: bool = False;
+}
+
+# Create + connect to root (auto-persists in SQLite)
+root ++> Item(title="Buy milk");
+
+# Query
+items = [root-->][?:Item];
+found = [root-->][?:Item](?title == "Buy milk")[0];
+
+# Delete
+del found;
+# or: root del--> found;
+```
+
+### 5. Frontend entry point in main.jac
+
+```jac
+cl import from .components.Layout { Layout }
+cl {
+    def:pub app() -> JsxElement { return <Layout />; }
+}
+```
+
+---
+
+## Frontend Rules (.cl.jac)
+
+### 6. Component props — ALWAYS use `props: dict`
+
+```jac
+# WRONG — individual params on JsxElement components
+def:pub Header(title: str, theme: str) -> JsxElement { ... }
+
+# RIGHT — always use props: dict, destructure inside
+def:pub Header(props: dict) -> JsxElement {
+    title = props.title or "";
+    theme = props.theme or "light";
+    return <header>{title}</header>;
+}
+
+# EXCEPTION: app(), layout(), page() take no props — that's fine
+def:pub app() -> JsxElement { return <Layout />; }
+```
+
+Components returning `JsxElement` MUST accept `props: dict` as the single parameter (or no params). NEVER use individual typed params like `(title: str, count: int)`.
+
+Also use `className`, NOT `class` for HTML attributes in JSX:
+```jac
+# WRONG
+<div class="container">
+
+# RIGHT
+<div className="container">
+```
+
+### 7. Jac syntax, NOT JavaScript
+
+```
+WRONG (JS)                          →  RIGHT (Jac)
+──────────────────────────────────────────────────
+const x = 5;                        →  x = 5;
+let items = [];                     →  has items: list = [];
+x ? a : b                           →  a if x else b
+() => { ... }                       →  def handler() -> None { ... }
+`hello ${name}`                     →  f"hello {name}"
+x === y                             →  x == y
+console.log(x)                      →  print(x)
+x.length                            →  len(x)
+parseInt(x)                         →  int(x)
+x.toString()                        →  str(x)
+items.map(fn)                       →  {[<Item /> for item in items]}
+items.filter(fn)                    →  [i for i in items if cond]
+items.push(x)                       →  items = items + [x];
+useEffect(() => {}, [])             →  can with entry { ... }
+useState(0)                         →  has count: int = 0;
+!condition                          →  not condition
+new Date()                          →  Reflect.construct(Date, [])
+window.open(url)                    →  globalThis.open(url, "_blank")
+```
+
+### 7. State — `has` auto-generates useState
+
+```jac
+has count: int = 0;        # auto-creates count + setCount
+has name: str = "";
+has items: list = [];
+
+count = count + 1;         # calls setCount internally
+items = items + [newItem]; # new reference = re-render
+```
+
+**NEVER define `setX` yourself. NEVER use `.append()` for state** — it mutates in place (no re-render). Always `items = items + [x]`.
+
+### 8. Effects — `can with entry/exit`
+
+```jac
+can with entry { ... }                  # mount (useEffect(fn, []))
+async can with entry { ... }            # async mount
+can with [dep1, dep2] entry { ... }     # dependency watch
+can with exit { ... }                   # cleanup/unmount
+```
+
+**NEVER use `useEffect(lambda...)` — that is OLD syntax.**
+
+### 9. Event handlers — NEVER inline in JSX
+
+```jac
+# WRONG — lambda in JSX
+<button onClick={lambda -> None { count = count + 1; }}>
+
+# WRONG — inline def
+<button onClick={def(e: any) -> None { count = count + 1; }}>
+
+# RIGHT — named function ABOVE return, passed by name
+def handle_click() -> None {
+    count = count + 1;
+}
+return <button onClick={handle_click}>Click</button>;
+```
+
+ALL event handlers must be named `def` functions defined BEFORE `return`.
+
+### 10. Functions MUST be defined BEFORE `return`
+
+```jac
+# WRONG — helper after return (unreachable)
+return <div>{render_item(data)}</div>;
+def render_item(d: dict) -> JsxElement { ... }
+
+# RIGHT — define above
+def render_item(d: dict) -> JsxElement { ... }
+return <div>{render_item(data)}</div>;
+```
+
+### 11. No comments inside JSX
+
+```jac
+# WRONG — all of these crash
+return <div>
+    {# comment}
+    <!-- HTML comment -->
+    {/* JS comment */}
+</div>;
+
+# RIGHT — comments ABOVE JSX
+# Render the list
+return <div>...</div>;
+```
+
+### 12. `sv import` — positional args ONLY
+
+In .cl.jac, kwargs compile to a SINGLE dict arg. Server gets wrong data.
+
+```jac
+# WRONG — kwargs
+resp = await calc(a=2, b=4, op="add");
+# Server receives: {"a": {"a":2, "b":4, "op":"add"}}
+
+# RIGHT — positional, order matches def:pub signature
+resp = await calc(2, 4, "add");
+```
+
+### 13. JS constructors need `Reflect.construct`
+
+In .cl.jac, `ClassName()` without `new` returns wrong type or throws. Jac has no `new` keyword.
+
+```jac
+# WRONG
+year = Date().getFullYear();          # CRASH: string has no method getFullYear
+ws = WebSocket("ws://localhost");     # CRASH: must be called with new
+
+# RIGHT
+year = Reflect.construct(Date, []).getFullYear();
+ws = Reflect.construct(WebSocket, ["ws://localhost"]);
+
+# Safe statics (no Reflect needed):
+Date.now();  JSON.parse();  Math.random();
+```
+
+Classes that ALWAYS need Reflect.construct: Date, WebSocket, TextDecoder, TextEncoder, URL, URLSearchParams, FormData, AbortController, RegExp, Error, Worker, Headers, Request, Response.
+
+### 14. Browser global name conflicts
+
+NEVER define functions named: `open`, `close`, `print`, `fetch`, `focus`, `blur`, `scroll`, `alert`, `confirm`, `prompt`, `stop`, `find`
+
+Use `handleOpen`, `handleClose`, `handleFetch`, etc.
+
+### 15. Display numbers/booleans with `str()`
+
+```jac
+# WRONG — may render nothing
+<span>{count}</span>
+
+# RIGHT
+<span>{str(count)}</span>
+```
+
+### 16. ALWAYS guard everything defensively
+
+Undefined access CRASHES the whole app in .cl.jac.
+
+```jac
+# State — always init with correct types, NEVER None
+has items: list = [];
+has user: dict = {};
+has loading: bool = True;
+
+# Dict access — use "key" in dict, not .get()
+name = item["name"] if "name" in item else "";
+
+# Async results — always wrap in try/except
+async can with entry {
+    try {
+        result = await get_items();
+        items = result or [];
+    } except Exception as e {
+        error = str(e);
+    }
+    loading = False;
+}
+
+# Props — always default
+items = props.items or [];
+title = props.title or "";
+```
+
+---
+
+## Import Rules (CRITICAL — memorize the pattern)
+
+### In .jac files (backend)
+
+```jac
+import from datetime { datetime }               # Python module
+cl import from .components.Layout { Layout }     # Client component (NO quotes, cl prefix)
+```
+
+### In .cl.jac files (frontend)
+
+```jac
+# Client-to-client — WITH quotes, DOTS not slashes
+import from ".Header" { Header }                 # same directory
+import from "..hooks.useTodos" { useTodos }      # parent directory
+import from "...lib.utils" { cn }                # 2 levels up
+
+# Server calls — sv import, NO quotes
+sv import from ..main { get_todos, add_todo }
+
+# NPM packages — WITH quotes
+import from "clsx" { cn }
+
+# Runtime — cl import, WITH quotes
+cl import from "@jac/runtime" { jacLogin, Outlet }
+
+# CSS — WITH quotes
+import "..styles.global.css";
+```
+
+### Dot level cheat sheet
+
+```
+.   = same directory
+..  = 1 level up (parent)
+... = 2 levels up
+```
+
+### NEVER do
+
+- `cl sv import` — never combine prefixes
+- `"..main"` with quotes on sv import — sv import has NO quotes
+- Slashes in import paths — always dots
+- File extensions in imports — never `.cl`, `.jac`, `.cl.jac`
+
+---
+
+## Project Structure
+
+```
+project-root/
+├── jac.toml            # config + deps
+├── main.jac            # ALL backend: nodes + endpoints + cl { app() }
+├── components/         # .cl.jac components (one per file)
+│   ├── Layout.cl.jac   # Root layout — imports child components
+│   ├── Header.cl.jac   # Nav/header
+│   └── ItemList.cl.jac # Data display (calls hook)
+├── hooks/              # .cl.jac data hooks (sv import + state)
+│   └── useItems.cl.jac
+├── pages/              # .jac file-based routing (optional)
+├── lib/                # .cl.jac shared utilities
+└── styles/             # CSS files
+```
+
+Layout.cl.jac is the root layout. Data logic lives in hooks/, called by child components — NOT by Layout.

jac_coder/data/rules/workflow.md

@@ -0,0 +1,88 @@
+# Coding Workflow & Validation Discipline
+
+> Follow this workflow EVERY TIME you write Jac code. No shortcuts.
+
+---
+
+## Before Writing Code
+
+1. **Read `jac.toml`** — check npm deps, project config, entry point.
+2. **Call `jac_docs(query)`** — look up syntax for what you're building. Do NOT guess.
+3. **If existing project**: call `analyze_project(directory)` to understand structure.
+4. **Call `jac_docs` again** before EACH new file type (`.jac` vs `.cl.jac` have different syntax).
+
+---
+
+## Build Order (fullstack apps)
+
+1. `main.jac` backend first — nodes + endpoints
+2. Hooks — `hooks/useX.cl.jac` (sv import from backend)
+3. Leaf components — `Header.cl.jac`, `ItemCard.cl.jac` (no data logic)
+4. Container components — `ItemList.cl.jac` (calls hooks, renders leaf components)
+5. Layout — `Layout.cl.jac` LAST (imports child components)
+6. App entry — `cl { def:pub app() }` in `main.jac`
+
+**Build dependencies bottom-up.** Never import a file that doesn't exist yet.
+
+---
+
+## While Writing Code
+
+- Use `write_code` / `edit_code` — they auto-run `jac_check` per file for syntax errors.
+- Do NOT call `jac_check` or `jac check` manually.
+- Do NOT use `run_command` for jac check.
+- If `write_code`/`edit_code` report errors → call `jac_docs(query)` to look up correct syntax → fix → retry.
+- Call `jac_docs` at least once every 3-4 tool calls. If unsure about ANY syntax, look it up immediately.
+- Use ABSOLUTE file paths for all operations.
+
+---
+
+## After Writing ALL Files
+
+### Step 1: Cross-file import check
+
+Before validating, manually verify:
+- Every `import from "..."` / `sv import from ...` references a file that exists
+- sv import function names match actual `def:pub` names in `main.jac`
+- Component imports use correct dot-levels (`.` same dir, `..` one up, `...` two up)
+- No duplicate component names or endpoint names across files
+
+### Step 2: Validate
+
+Call `validate_project(directory)` ONCE after all files are written.
+- It batch type-checks all `.jac` files
+- It auto-fixes common patterns (root→root(), (?:)→[?:])
+- It returns all type errors with hints
+
+### Step 3: Fix and re-validate
+
+- Read the report from `validate_project`
+- Fix all remaining errors
+- Call `validate_project()` again to confirm clean
+
+### Step 4: Preview log check (fullstack apps)
+
+- Read the LAST 50 lines of `.jac-preview.log`
+- Look for: `[Client]`, `ERROR`, `Exception`, `undefined`, `module not found`
+- Common runtime errors:
+  - "module not found" → file doesn't exist OR stale HMR cache
+  - "undefined" → missing prop, uninitialized state, wrong import
+  - "Function X failed" → sv import name doesn't match backend def:pub
+  - "422" → request body schema mismatch
+
+---
+
+## When Stuck
+
+1. Call `jac_docs(query)` — look up the correct syntax
+2. Call `analyze_project` or `find_symbol` — check existing patterns
+3. If same error 2-3 times → `ask_question` to ask the user
+4. If editing same file 3+ times → step back, check assumptions
+
+---
+
+## HMR "module not found" Fix
+
+1. File exists but compiled JS is stale
+2. Do trivial edit on the TARGET file (not the importing file) — add a blank line
+3. HMR recompiles, import resolves

jac_coder/events.jac

@@ -0,0 +1,110 @@
+import time;
+import threading;
+
+glob _tl = threading.local();
+
+
+def _callbacks() -> list {
+    if not hasattr(_tl, "callbacks") {
+        _tl.callbacks = [];
+    }
+    return _tl.callbacks;
+}
+
+
+def register_event_callback(cb: Any) -> None {
+    _callbacks().append(cb);
+}
+
+def clear_event_callbacks() -> None {
+    _tl.callbacks = [];
+}
+
+def next_step() -> int {
+    if not hasattr(_tl, "step_counter") {
+        _tl.step_counter = 0;
+    }
+    if not hasattr(_tl, "turn_tools") {
+        _tl.turn_tools = 0;
+    }
+    _tl.step_counter += 1;
+    _tl.turn_tools += 1;
+    return _tl.step_counter;
+}
+
+def reset_steps() -> None {
+    _tl.step_counter = 0;
+    _tl.active_tool = {};
+}
+
+def get_active_tool() -> dict {
+    return getattr(_tl, "active_tool", {});
+}
+
+def set_active_tool(info: dict) -> None {
+    _tl.active_tool = info;
+}
+
+def set_agent_prefix(prefix: str) -> None {
+    _tl.agent_prefix = prefix;
+}
+
+def get_agent_prefix() -> str {
+    return getattr(_tl, "agent_prefix", "");
+}
+
+def start_turn() -> None {
+    _tl.turn_start = time.time();
+    _tl.turn_tools = 0;
+    _tl.turn_errors = 0;
+    _tl.turn_files = [];
+}
+
+def track_file(path: str) -> None {
+    if not hasattr(_tl, "turn_files") {
+        _tl.turn_files = [];
+    }
+    if path and path not in _tl.turn_files {
+        _tl.turn_files.append(path);
+    }
+}
+
+def track_error() -> None {
+    if not hasattr(_tl, "turn_errors") {
+        _tl.turn_errors = 0;
+    }
+    _tl.turn_errors += 1;
+}
+
+def emit_turn_summary() -> dict {
+    turn_start = getattr(_tl, "turn_start", 0.0);
+    turn_tools = getattr(_tl, "turn_tools", 0);
+    turn_errors = getattr(_tl, "turn_errors", 0);
+    turn_files = getattr(_tl, "turn_files", []);
+    duration_s = round(time.time() - turn_start, 1) if turn_start > 0 else 0.0;
+    summary = {
+        "tools_count": turn_tools,
+        "files_modified": list(turn_files),
+        "errors": turn_errors,
+        "duration_s": duration_s
+    };
+    emit_event("turn_summary", summary);
+    return summary;
+}
+
+def emit_event(event_type: str, data: dict) -> None {
+    cbs = _callbacks();
+    if not cbs {
+        return;
+    }
+    data["timestamp"] = time.time();
+    data["event_type"] = event_type;
+    for cb in list(cbs) {
+        try {
+            cb(event_type, data);
+        } except Exception as e {
+            import sys;
+            sys.stderr.write(f"[events] callback error: {e}\n");
+        }
+    }
+}