tjs-lang 0.7.7 → 0.7.8

package/llms.txt

@@ -0,0 +1,79 @@
+# tjs-lang
+
+> A typed JavaScript platform: TJS (a TS-like language with runtime type validation), AJS (a gas-metered VM for executing untrusted agent code), and a single-pass toolchain (transpile + lint + test + docs). Types survive to runtime as contracts, examples, and tests. Inline WASM, monadic errors, safe eval, capability-based sandboxing.
+
+This file is a navigation index for AI agents. It does not contain the docs themselves — it points to them. Read the linked files in the order suggested below.
+
+## Read this first (avoids the #1 LLM mistake)
+
+- [CLAUDE-TJS-SYNTAX.md](CLAUDE-TJS-SYNTAX.md) — TJS syntax reference. Critical: `function foo(x: 'default')` is NOT a TypeScript string-literal type. The colon value is an **example**; `'default'` widens to `string`. LLMs get this wrong constantly.
+- [CLAUDE.md](CLAUDE.md) — project overview, common commands, architecture, security model, and key APIs.
+
+## Language guides
+
+- [DOCS-TJS.md](DOCS-TJS.md) — TJS language guide (the long form).
+- [DOCS-AJS.md](DOCS-AJS.md) — AJS runtime guide (gas-metered sandboxed VM).
+- [TJS-FOR-JS.md](TJS-FOR-JS.md) — for JavaScript developers: syntax differences, gotchas.
+- [TJS-FOR-TS.md](TJS-FOR-TS.md) — for TypeScript developers: migration, interop, what changes.
+- [guides/tjs.md](guides/tjs.md) and [guides/ajs.md](guides/ajs.md) — usage-oriented walkthroughs.
+- [guides/patterns.md](guides/patterns.md) — common patterns and idioms.
+- [guides/tjs-examples.md](guides/tjs-examples.md) — annotated example programs.
+- [guides/footguns.md](guides/footguns.md) — JS footguns TJS quietly fixes (boxed-primitive coercion, ==/!=, typeof null, uninitialized let, etc.).
+- [guides/playground-imports.md](guides/playground-imports.md) — how the playground resolves `import` statements: TFS service worker, default JSDelivr `/+esm`, esm.sh allowlist for React, CDN hints (`jsdelivr/`, `esmsh/`, `unpkg/`, `github/`), full-URL passthrough.
+- [guides/ajs-llm-prompt.md](guides/ajs-llm-prompt.md) — prompt template for asking LLMs to write AJS.
+
+## Architecture and internals
+
+- [CONTEXT.md](CONTEXT.md) — architecture deep dive (two-layer design, atom system, value resolution).
+- [docs/function-predicate-design.md](docs/function-predicate-design.md) — Type / Generic / FunctionPredicate design.
+- [docs/generic-dts-design.md](docs/generic-dts-design.md) — `.d.ts` generation from TJS.
+- [docs/WASM-QUICKSTART.md](docs/WASM-QUICKSTART.md) — inline WASM, SIMD, `wasmBuffer()`.
+- [docs/native-engine-integration.md](docs/native-engine-integration.md) — embedding into a native runtime.
+
+## Examples and live code
+
+- [examples/](examples/) — standalone `.tjs` example files (`hello.tjs`, `datetime.tjs`, `generic-demo.tjs`, `js-footguns-fixed.tjs`).
+- [tjs-src/](tjs-src/) — the TJS runtime, written in TJS itself (self-hosting reference).
+- Playground: https://tjs-platform.web.app — try TJS in a browser.
+
+## Package entry points (what to import)
+
+- `tjs-lang` → `src/index.ts` — main entry: `Agent`, `AgentVM`, `ajs`, `tjs`.
+- `tjs-lang/lang` → `src/lang/transpiler.ts` — language tools only: `tjs`, `transpile`.
+- `tjs-lang/lang/from-ts` → `src/lang/emitters/from-ts.ts` — TypeScript → TJS/JS transpilation.
+- `tjs-lang/vm` → `src/vm/index.ts` — VM and atoms.
+- `tjs-lang/eval` → `src/lang/eval.ts` — `Eval`, `SafeFunction`.
+- `tjs-lang/batteries` → `src/batteries/index.ts` — LM Studio integration (lazy, local-only).
+
+## Source map (for code-reading agents)
+
+- `src/lang/parser.ts` — TJS parser (colon shorthand, safety markers, return-type extraction).
+- `src/lang/parser-transforms.ts` — Type / Generic / FunctionPredicate block transforms.
+- `src/lang/emitters/js.ts` — emits JavaScript with `__tjs` metadata.
+- `src/lang/emitters/from-ts.ts` — TypeScript → TJS/JS, including class metadata.
+- `src/lang/emitters/dts.ts` — `.d.ts` generation.
+- `src/lang/runtime.ts` — TJS runtime: monadic errors, `checkType`, `createRuntime`.
+- `src/lang/inference.ts` — infer `TypeDescriptor` from example values.
+- `src/lang/json-schema.ts` — JSON Schema from `TypeDescriptor`.
+- `src/lang/wasm.ts` — WASM bytecode emission.
+- `src/lang/linter.ts` — static analysis (unused vars, unreachable code).
+- `src/vm/runtime.ts` — atom implementations, expression sandboxing, fuel charging (security-critical, ~3000 lines).
+- `src/vm/vm.ts` — `AgentVM` class.
+- `src/vm/atoms/` — individual atom definitions; `batteries.ts` has LLM/vector/store atoms.
+- `src/builder.ts` — fluent `TypedBuilder` API for constructing AST without source.
+- `src/cli/tjs.ts` — CLI: `check`, `run`, `types`, `emit`, `convert`, `test`.
+
+## Common gotchas
+
+- `tjs(source)` returns `{ code, types, metadata, testResults, ... }`. Use `.code` for the transpiled JS string.
+- Errors are `MonadicError` (check with `isMonadicError()`), not native `Error`. Errors are returned, not thrown.
+- AJS: `null.foo.bar` returns `undefined` (uses `?.` semantics) — does NOT throw like JS.
+- AJS: computed member access with variables (`items[i]`) is a transpile-time error; use `.map`/`.reduce` atoms.
+- Native TJS has all safety modes ON by default. `TjsCompat` disables them. `fromTS` output has them OFF unless `TjsStrict` is added.
+
+## Tracking and process
+
+- [TODO.md](TODO.md) — open work, organized by area. Move done items to the **Completed** section.
+- [PLAN.md](PLAN.md) — roadmap.
+- [AGENTS.md](AGENTS.md) — session-completion checklist (canonical). Hard rule: not done until `git push` succeeds.
+- [README.md](README.md) — public-facing pitch.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tjs-lang",
-  "version": "0.7.7",
+  "version": "0.7.8",
   "description": "Type-safe JavaScript dialect with runtime validation, sandboxed VM execution, and AI agent orchestration. Transpiles TypeScript to validated JS with fuel-metered execution for untrusted code.",
   "keywords": [
     "typescript",
@@ -76,7 +76,8 @@
     "demo",
     "tjs-lang.svg",
     "CONTEXT.md",
-    "CLAUDE.md"
+    "CLAUDE.md",
+    "llms.txt"
   ],
   "sideEffects": false,
   "repository": {

package/src/cli/commands/convert.test.ts

@@ -1,10 +1,13 @@
 import { describe, it, expect, beforeAll, afterAll } from 'bun:test'
 import { mkdtempSync, writeFileSync, readFileSync, rmSync } from 'fs'
-import { join } from 'path'
+import { join, resolve } from 'path'
 import { tmpdir } from 'os'
 import { fromTS } from '../../lang/emitters/from-ts'
 import { tjs } from '../../lang'
 
+const REPO_ROOT = resolve(import.meta.dir, '../../..')
+const BUN = process.execPath
+
 const TS_SIMPLE = `
 function greet(name: string): string {
   return \`Hello, \${name}!\`
@@ -146,8 +149,8 @@ function getAge(): number { return 30 }
       const inputPath = join(tmpDir, 'hello.ts')
       writeFileSync(inputPath, TS_SIMPLE)
 
-      const proc = Bun.spawn(['bun', 'src/cli/tjs.ts', 'convert', inputPath], {
-        cwd: '/Users/tonioloewald/tjs-lang',
+      const proc = Bun.spawn([BUN, 'src/cli/tjs.ts', 'convert', inputPath], {
+        cwd: REPO_ROOT,
         stdout: 'pipe',
         stderr: 'pipe',
       })
@@ -165,8 +168,8 @@ function getAge(): number { return 30 }
       writeFileSync(inputPath, TS_SIMPLE)
 
       const proc = Bun.spawn(
-        ['bun', 'src/cli/tjs.ts', 'convert', '--emit-tjs', inputPath],
-        { cwd: '/Users/tonioloewald/tjs-lang', stdout: 'pipe', stderr: 'pipe' }
+        [BUN, 'src/cli/tjs.ts', 'convert', '--emit-tjs', inputPath],
+        { cwd: REPO_ROOT, stdout: 'pipe', stderr: 'pipe' }
       )
       const stdout = await new Response(proc.stdout).text()
       await proc.exited
@@ -181,8 +184,8 @@ function getAge(): number { return 30 }
       writeFileSync(inputPath, TS_WITH_TESTS)
 
       const proc = Bun.spawn(
-        ['bun', 'src/cli/tjs.ts', 'convert', '-V', inputPath],
-        { cwd: '/Users/tonioloewald/tjs-lang', stdout: 'pipe', stderr: 'pipe' }
+        [BUN, 'src/cli/tjs.ts', 'convert', '-V', inputPath],
+        { cwd: REPO_ROOT, stdout: 'pipe', stderr: 'pipe' }
       )
       const stderr = await new Response(proc.stderr).text()
       await proc.exited
@@ -194,8 +197,8 @@ function getAge(): number { return 30 }
       const inputPath = join(tmpDir, 'failing.ts')
       writeFileSync(inputPath, TS_WITH_FAILING_TEST)
 
-      const proc = Bun.spawn(['bun', 'src/cli/tjs.ts', 'convert', inputPath], {
-        cwd: '/Users/tonioloewald/tjs-lang',
+      const proc = Bun.spawn([BUN, 'src/cli/tjs.ts', 'convert', inputPath], {
+        cwd: REPO_ROOT,
         stdout: 'pipe',
         stderr: 'pipe',
       })
@@ -227,8 +230,8 @@ function getAge(): number { return 30 }
       writeFileSync(join(srcDir, 'types.d.ts'), `// declaration file`)
 
       const proc = Bun.spawn(
-        ['bun', 'src/cli/tjs.ts', 'convert', srcDir, '-o', outDir],
-        { cwd: '/Users/tonioloewald/tjs-lang', stdout: 'pipe', stderr: 'pipe' }
+        [BUN, 'src/cli/tjs.ts', 'convert', srcDir, '-o', outDir],
+        { cwd: REPO_ROOT, stdout: 'pipe', stderr: 'pipe' }
       )
       await proc.exited
 
@@ -258,16 +261,8 @@ function getAge(): number { return 30 }
       )
 
       const proc = Bun.spawn(
-        [
-          'bun',
-          'src/cli/tjs.ts',
-          'convert',
-          '--emit-tjs',
-          srcDir,
-          '-o',
-          outDir,
-        ],
-        { cwd: '/Users/tonioloewald/tjs-lang', stdout: 'pipe', stderr: 'pipe' }
+        [BUN, 'src/cli/tjs.ts', 'convert', '--emit-tjs', srcDir, '-o', outDir],
+        { cwd: REPO_ROOT, stdout: 'pipe', stderr: 'pipe' }
       )
       await proc.exited
 

package/src/lang/bool-coercion.test.ts

@@ -0,0 +1,203 @@
+/**
+ * Boolean coercion rewriter tests.
+ *
+ * Verifies that `Boolean(new Boolean(false)) === true` and friends are
+ * fixed under TjsStandard mode.
+ */
+
+import { describe, it, expect, beforeEach } from 'bun:test'
+import { transpileToJS } from './emitters/js'
+import { createRuntime } from './runtime'
+
+function run(src: string): any {
+  const r = transpileToJS(src)
+  ;(globalThis as any).__tjs = createRuntime()
+  try {
+    const fn = new Function(r.code + '\nreturn f')()
+    return fn()
+  } finally {
+    delete (globalThis as any).__tjs
+  }
+}
+
+function emit(src: string): string {
+  return transpileToJS(src).code
+}
+
+describe('Boolean coercion rewriter (TjsStandard)', () => {
+  beforeEach(() => {
+    delete (globalThis as any).__tjs
+  })
+
+  describe('truthiness contexts unwrap boxed primitives', () => {
+    it('fixes `if (new Boolean(false))`', () => {
+      const out = run(
+        `function f(){ if (new Boolean(false)) return 'truthy'; return 'falsy' }`
+      )
+      expect(out).toBe('falsy')
+    })
+
+    it('fixes `while (new Boolean(false))`', () => {
+      const out = run(
+        `function f(){ let n = 0; const g = new Boolean(false); while (g) { n++; if (n>2) break }; return n }`
+      )
+      expect(out).toBe(0)
+    })
+
+    it('fixes `do {} while (new Boolean(false))`', () => {
+      const out = run(
+        `function f(){ let n = 0; const g = new Boolean(false); do { n++ } while (g && n < 3); return n }`
+      )
+      expect(out).toBe(1) // body runs once, then condition is checked & is false
+    })
+
+    it('fixes `for (_; new Boolean(false); _)`', () => {
+      const out = run(
+        `function f(){ let n = 0; const g = new Boolean(false); for (let i = 0; g; i++) { n++; if (n>2) break }; return n }`
+      )
+      expect(out).toBe(0)
+    })
+
+    it('fixes `!new Boolean(false)`', () => {
+      const out = run(`function f(){ return !new Boolean(false) }`)
+      expect(out).toBe(true)
+    })
+
+    it('fixes `new Boolean(false) ? a : b`', () => {
+      const out = run(`function f(){ return new Boolean(false) ? 'a' : 'b' }`)
+      expect(out).toBe('b')
+    })
+
+    it('fixes `Boolean(new Boolean(false))`', () => {
+      const out = run(`function f(){ return Boolean(new Boolean(false)) }`)
+      expect(out).toBe(false)
+    })
+  })
+
+  describe('logical operators preserve value-returning semantics', () => {
+    it('`new Boolean(false) || x` returns x', () => {
+      const out = run(`function f(){ return (new Boolean(false)) || 'right' }`)
+      expect(out).toBe('right')
+    })
+
+    it('`new Boolean(true) || x` returns the wrapper (truthy LHS wins)', () => {
+      const out = run(`function f(){ return (new Boolean(true)) || 'right' }`)
+      // LHS is truthy after unwrap, so JS-style && returns the original LHS
+      expect(typeof out).toBe('object')
+      expect(out.valueOf()).toBe(true)
+    })
+
+    it('`new Boolean(false) && x` returns the wrapper (falsy LHS short-circuits)', () => {
+      const out = run(`function f(){ return (new Boolean(false)) && 'right' }`)
+      expect(typeof out).toBe('object')
+      expect(out.valueOf()).toBe(false)
+    })
+
+    it('`new Boolean(true) && x` returns x', () => {
+      const out = run(`function f(){ return (new Boolean(true)) && 'right' }`)
+      expect(out).toBe('right')
+    })
+
+    it("`a || b` doesn't double-evaluate side effects", () => {
+      const out = run(
+        `function f(){ let n = 0; const inc = () => { n++; return new Boolean(false) }; const r = inc() || inc(); return n }`
+      )
+      expect(out).toBe(2) // both inc() called once each
+    })
+  })
+
+  describe('nested coercion contexts', () => {
+    it('handles `if (a && b)`', () => {
+      const out = run(
+        `function f(){ const a = new Boolean(false); const b = true; if (a && b) return 'in'; return 'out' }`
+      )
+      expect(out).toBe('out')
+    })
+
+    it('handles `if (!(a && b))`', () => {
+      const out = run(
+        `function f(){ const a = new Boolean(false); const b = true; if (!(a && b)) return 'not'; return 'is' }`
+      )
+      expect(out).toBe('not')
+    })
+
+    it('handles `f(a && b)` (LogicalExpression inside CallExpression)', () => {
+      const out = run(
+        `function f(){ const a = new Boolean(false); const id = (x) => x; const r = id(a && true); return Boolean(r) }`
+      )
+      expect(out).toBe(false)
+    })
+  })
+
+  describe('does not break normal JS', () => {
+    it('truthy primitives still truthy', () => {
+      const out = run(`function f(){ if (1) return 'in'; return 'out' }`)
+      expect(out).toBe('in')
+    })
+
+    it('falsy primitives still falsy', () => {
+      const out = run(`function f(){ if (0) return 'in'; return 'out' }`)
+      expect(out).toBe('out')
+    })
+
+    it('plain objects still truthy', () => {
+      const out = run(`function f(){ if ({}) return 'in'; return 'out' }`)
+      expect(out).toBe('in')
+    })
+
+    it('arrays still truthy', () => {
+      const out = run(`function f(){ if ([]) return 'in'; return 'out' }`)
+      expect(out).toBe('in')
+    })
+
+    it('?? is unchanged (only checks null/undefined, not truthy)', () => {
+      const out = run(`function f(){ return null ?? 'fallback' }`)
+      expect(out).toBe('fallback')
+    })
+
+    it('`new Boolean(false) ?? x` returns the wrapper (it is not null/undef)', () => {
+      const out = run(`function f(){ return (new Boolean(false)) ?? 'x' }`)
+      expect(typeof out).toBe('object')
+    })
+
+    it('`Boolean(true)` (no boxed arg) still returns true', () => {
+      const out = run(`function f(){ return Boolean(1) }`)
+      expect(out).toBe(true)
+    })
+  })
+
+  describe('mode gating', () => {
+    it('TjsCompat disables the rewrite (preserves JS footgun)', () => {
+      const r = transpileToJS(
+        `TjsCompat\nfunction f(){ if (new Boolean(false)) return 'truthy'; return 'falsy' }`
+      )
+      ;(globalThis as any).__tjs = createRuntime()
+      try {
+        const fn = new Function(r.code + '\nreturn f')()
+        // Native JS behavior: boxed Boolean(false) is truthy
+        expect(fn()).toBe('truthy')
+      } finally {
+        delete (globalThis as any).__tjs
+      }
+    })
+
+    it('emits __tjs.toBool calls under TjsStandard', () => {
+      const code = emit(`function f(){ if (x) return 1 }`)
+      expect(code).toContain('__tjs.toBool(')
+    })
+
+    it('does not emit __tjs.toBool calls under TjsCompat', () => {
+      const code = emit(`TjsCompat\nfunction f(){ if (x) return 1 }`)
+      expect(code).not.toContain('__tjs.toBool(')
+    })
+  })
+
+  describe('inline-runtime fallback includes toBool', () => {
+    it('emitted code includes toBool function when used', () => {
+      const code = emit(`function f(){ if (x) return 1 }`)
+      // Under TjsStandard, the rewrite is applied → __tjs.toBool is referenced
+      // → inline runtime includes the function definition
+      expect(code).toContain('function toBool')
+    })
+  })
+})