tjs-lang 0.7.6 → 0.7.8

package/CLAUDE.md

@@ -12,6 +12,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - **AJS** — Agent language that compiles to JSON AST for safe, sandboxed execution with fuel limits and injected capabilities. Code travels to data.
 - **Toolchain** — Compresses transpilation, linting, testing, and documentation generation into one pass. Includes inline WASM with SIMD, polymorphic dispatch, local class extensions, and a browser-based playground.
 
+> **TJS syntax is NOT TypeScript.** Full reference: [`CLAUDE-TJS-SYNTAX.md`](CLAUDE-TJS-SYNTAX.md). The single most common LLM mistake is treating `function foo(x: 'default')` as a TypeScript string-literal type. It is _not_ — the colon value is an **example**, and `'default'` widens to `string`. See the syntax doc before writing or modifying TJS source.
+
 ## Common Commands
 
 ```bash
@@ -52,13 +54,7 @@ bun run docs                # Generate documentation
 # Build standalone CLI binaries
 bun run build:cli           # Compiles tjs + tjsx to dist/
 
-# Compatibility testing (transpile popular TS libraries with fromTS)
-bun scripts/compat-zod.ts          # Zod validation library
-bun scripts/compat-effect.ts       # Effect (HKTs, intersections)
-bun scripts/compat-radash.ts       # Radash utilities
-bun scripts/compat-superstruct.ts  # Superstruct validation
-bun scripts/compat-ts-pattern.ts   # ts-pattern matching
-bun scripts/compat-kysely.ts       # Kysely SQL builder
+# Compatibility testing — see scripts/compat-*.ts (zod, effect, radash, superstruct, ts-pattern, kysely)
 
 # Deployment (Firebase)
 bun run deploy              # Build demo + deploy functions + hosting
@@ -72,15 +68,15 @@ bun run functions:serve     # Local functions emulator
 ### Two-Layer Design
 
 1. **Builder Layer** (`src/builder.ts`): Fluent API that constructs AST nodes. Contains no execution logic.
-2. **Runtime Layer** (`src/vm/runtime.ts`): Executes AST nodes. Contains all atom implementations (~2900 lines, security-critical).
+2. **Runtime Layer** (`src/vm/runtime.ts`): Executes AST nodes. Contains all atom implementations (~3024 lines, security-critical).
 
 ### Key Source Files
 
 - `src/index.ts` - Main entry, re-exports everything
-- `src/vm/runtime.ts` - All atom implementations, expression evaluation, fuel charging (~3000 lines, security-critical)
-- `src/vm/vm.ts` - AgentVM class (~226 lines)
+- `src/vm/runtime.ts` - All atom implementations, expression evaluation, fuel charging (~3024 lines, security-critical)
+- `src/vm/vm.ts` - AgentVM class (~247 lines)
 - `src/vm/atoms/batteries.ts` - Battery atoms (vector search, LLM, store operations)
-- `src/builder.ts` - TypedBuilder fluent API (~19KB)
+- `src/builder.ts` - TypedBuilder fluent API (~757 lines / ~19KB)
 - `src/lang/parser.ts` - TJS parser with colon shorthand, unsafe markers, return type extraction
 - `src/lang/parser-transforms.ts` - Type, Generic, and FunctionPredicate block/function form transforms
 - `src/lang/emitters/ast.ts` - Emits Agent99 AST from parsed source
@@ -97,7 +93,7 @@ bun run functions:serve     # Local functions emulator
 - `src/batteries/` - LM Studio integration (lazy init, model audit, vector search)
 - `src/store/` - Store implementations for persistence
 - `src/rbac/` - Role-based access control
-- `src/use-cases/` - Integration tests and real-world examples (28 test files)
+- `src/use-cases/` - Integration tests and real-world examples (30 test files)
 - `src/cli/tjs.ts` - CLI tool for check/run/types/emit/convert/test commands
 - `src/cli/tjsx.ts` - JSX/component runner
 - `src/cli/playground.ts` - Local playground server
@@ -138,6 +134,9 @@ import { Agent, AgentVM, ajs, tjs } from 'tjs-lang' // Main entry
 import { Eval, SafeFunction } from 'tjs-lang/eval' // Safe eval utilities
 import { tjs, transpile } from 'tjs-lang/lang' // Language tools only
 import { fromTS } from 'tjs-lang/lang/from-ts' // TypeScript transpilation
+import { AgentVM } from 'tjs-lang/vm' // VM only (smaller bundle)
+import { batteryAtoms } from 'tjs-lang/batteries' // LM Studio batteries
+// Editor integrations: 'tjs-lang/editors/monaco', '/codemirror', '/ace'
 ```
 
 ### Transpiler Chain (TS → TJS → JS)
@@ -246,7 +245,7 @@ AJS expressions behave differently from JavaScript in several important ways:
 - Unit tests alongside source files (`*.test.ts`)
 - Integration tests in `src/use-cases/` (RAG, orchestration, malicious actors)
 - Security tests in `src/use-cases/malicious-actor.test.ts`
-- Language tests split across 14 files in `src/lang/` (lang.test.ts, features.test.ts, codegen.test.ts, parser.test.ts, from-ts.test.ts, wasm.test.ts, etc.)
+- Language tests split across 17 files in `src/lang/` (lang.test.ts, features.test.ts, codegen.test.ts, parser.test.ts, from-ts.test.ts, wasm.test.ts, etc.)
 
 Coverage targets: 98% lines on `src/vm/runtime.ts` (security-critical), 80%+ overall.
 
@@ -399,6 +398,66 @@ The playground is hosted on Firebase (`tjs-platform.web.app`). Demo build output
 
 The `docs/` directory contains real documentation (markdown), not build artifacts. See `docs/README.md` for the documentation index.
 
+### Playground Examples
+
+The playground (https://tjs-platform.web.app) shows interactive TJS and AJS examples in a navigable sidebar. Examples live as markdown files with embedded code blocks, NOT as raw `.tjs` files.
+
+**Where they live:**
+
+- TJS playground examples: `guides/examples/tjs/<slug>.md`
+- AJS playground examples: `guides/examples/ajs/<slug>.md` (assumed parallel structure)
+
+**File format:**
+
+<!-- prettier-ignore -->
+```markdown
+<!--{"section":"tjs","type":"example","group":"basics","order":16}-->
+
+# Example Title
+
+Short intro paragraph (plain markdown).
+
+​```tjs
+/*#
+## Optional H2 — markdown rendered above the code in the playground
+Explain the concept here. Use markdown freely.
+*/
+
+// Then the actual TJS code
+function demo() { ... }
+
+test 'a description' {
+  expect(...).toBe(...)
+}
+​```
+```
+
+Frontmatter fields: `section` (`tjs`/`ajs`), `type: "example"`, `group` (`basics`/`advanced`/etc.), `order` (numeric, controls sidebar position). The H1 becomes the example title in the nav.
+
+**Registration:**
+
+Examples are auto-discovered by `bin/docs.js` (run via `bun run docs`), which walks the markdown tree, parses frontmatter, extracts the `tjs`/`ajs` code block, and writes the result to `demo/docs.json`. The demo loads `docs.json` at runtime — no other registration step.
+
+**After adding/editing an example:** run `bun run docs` and commit the regenerated `demo/docs.json` alongside the `.md` file. (The docs builder also runs as part of `bun run build:demo` and `bun run deploy`.)
+
+**Testing playground examples:**
+
+The CLI (`bun src/cli/tjs.ts run`) does NOT inject the test-block `expect` harness — that's a playground-only thing. So running an extracted code block via the CLI prints "expect is not defined" for any `test { expect(...) }` blocks even though they pass in the playground. To verify an example:
+
+1. **Console-log behavior** (works via CLI): extract the `tjs` code block and run it.
+
+   ````bash
+   awk '/^```tjs$/{flag=1; next} /^```$/{flag=0} flag' \
+     guides/examples/tjs/<slug>.md > /tmp/example.tjs
+   bun src/cli/tjs.ts run /tmp/example.tjs
+   ````
+
+   Verify the printed output matches the expected behavior shown in the example's comments.
+
+2. **Test blocks**: spin up the dev server (`bun run start`) and load the example in the playground UI to confirm tests pass under the real `expect` harness.
+
+3. **Frontmatter / registration**: after `bun run docs`, grep `demo/docs.json` for the slug to confirm it was picked up with the right `section`/`group`/`order`.
+
 ### Additional Directories
 
 - `tjs-src/` — TJS runtime written in TJS itself (self-hosting)
@@ -408,31 +467,47 @@ The `docs/` directory contains real documentation (markdown), not build artifact
 
 ### Additional Documentation
 
+- `llms.txt` — agent-facing navigation index (ships in npm bundle); points to docs and source entry points
+- `guides/footguns.md` — JS footguns TJS fixes (boxed-primitive truthiness, `==` coercion, `typeof null`, uninitialized `let`, etc.). Demo: `examples/js-footguns-fixed.tjs`.
+- `guides/playground-imports.md` — how the playground/dev-server resolves bare imports: TFS service worker, default JSDelivr `/+esm` routing, esm.sh allowlist for peer-dep packages (React), CDN hints (`jsdelivr/`, `esmsh/`, `unpkg/`, `github/`), and full-URL passthrough.
+- `README.md` — Project intro, install, quick start
 - `DOCS-TJS.md` — TJS language guide
 - `DOCS-AJS.md` — AJS runtime guide
 - `TJS-FOR-JS.md` — TJS guide for JavaScript developers (syntax differences, gotchas)
 - `TJS-FOR-TS.md` — TJS guide for TypeScript developers (migration, interop)
 - `CONTEXT.md` — Architecture deep dive
-- `AGENTS.md` — Agent workflow instructions (issue tracking with `bd`, mandatory push-before-done)
+- `AGENTS.md` — Agent workflow instructions (session-completion checklist, push-before-done rule)
+- `TODO.md` — Open work, organized by area; move items to the **Completed** section when done
 - `PLAN.md` — Roadmap
+- `MANIFESTO-BUILDER.md` / `MANIFESTO-ENTERPRISE.md` — Positioning docs (audience-targeted pitches)
+- `benchmarks.md` — Top-level benchmark results (separate from `guides/benchmarks.md`)
 
-### Issue Tracking with `bd`
+### Keeping This File and `llms.txt` Current
 
-The project uses `bd` (beads) for issue tracking. Key commands:
+Update both files when you change something an agent needs to discover:
 
-```bash
-bd ready                          # Find available work
-bd show <id>                      # View issue details
-bd update <id> --status in_progress  # Claim work
-bd close <id>                     # Complete work
-bd sync                           # Sync with git
-```
+- **New top-level markdown doc** → add to "Additional Documentation" here AND to the appropriate section of `llms.txt`.
+- **New package entry point** (subpath export in `package.json`) → add to "Package Entry Points" here AND to "Package entry points" in `llms.txt`.
+- **New CLI command or `bun run` script** → add to "Common Commands".
+- **Renamed or moved key source file** → update "Key Source Files" here AND "Source map" in `llms.txt`.
+- **New language mode / safety directive** → add to the TJS Syntax Reference section.
+- **New playground example** → add to `guides/examples/{tjs,ajs}/<slug>.md`, then `bun run docs` to regenerate `demo/docs.json`. See "Playground Examples" above.
+
+Skip stale-prone precision (exact line counts, file sizes) for new entries — they drift silently. The existing `~3024` etc. are kept current opportunistically, not on every commit.
+
+### Tracking Work
+
+Work is tracked in plain markdown — no external issue tracker. Open items live in `TODO.md` (organized by area). When you start a task, find or add the relevant entry; when you finish, check the box and (for substantial work) move it to the Completed section with a short note.
+
+### Landing the Plane (Session Completion Checklist)
 
-**Critical rule**: Work is NOT complete until `git push` succeeds. Never stop before pushing — work stranded locally is work lost. If push fails, resolve and retry.
+See `AGENTS.md` for the canonical session-completion checklist. Hard rule: work is not complete until `git push` succeeds — never stop before pushing, never `--no-verify` to bypass hooks.
 
-### Known Gotcha: `tjs()` Returns an Object, Not a String
+### Common Gotchas
 
-`tjs(source)` returns `{ code, types, metadata, testResults, ... }`. Use `.code` to get the transpiled JavaScript string. This is a common mistake.
+- **`tjs(source)` returns an object, not a string.** It returns `{ code, types, metadata, testResults, ... }` — use `.code` for the transpiled JS string.
+- **Prettier mangles bare-expression code blocks in markdown.** Code blocks tagged ` ```js` get reformatted; bare expressions like `'5' == 5` and `[1] == 1` on consecutive lines collapse into one expression with ASI guards. Use `<!-- prettier-ignore -->` directly above the code fence to preserve hand-formatted JS examples (or tag the block as `text`/`tjs`/`ts` instead — Prettier ignores those).
+- **`tjs-lang` package alias only works inside the project** (set in `bunfig.toml`). Test scripts written in `/tmp` won't resolve `import { tjs } from 'tjs-lang/lang'` to the local source — they'll resolve to whatever's in `node_modules`. For ad-hoc experiments outside the repo, use absolute paths: `import { tjs } from '/Users/.../tjs-lang/src/lang/index'`.
 
 ### Running Emitted TJS Code
 

package/bin/docs.js

@@ -54,7 +54,10 @@ function extractDescription(content) {
 }
 
 function metadata(content, filePath) {
-  let source = content.match(/<\!\-\-(\{.*\})\-\->|\/\*(\{.*\})\*\//)
+  // Only the FIRST non-blank line may be frontmatter. Matching anywhere in
+  // the file produces false positives when docs document the format itself
+  // (e.g. CLAUDE.md showing an example of <!--{...}--> ).
+  let source = content.match(/^\s*(?:<\!\-\-(\{.*\})\-\->|\/\*(\{.*\})\*\/)/)
   let data = {}
   if (source) {
     try {