plainscript-lang 0.1.7-latest

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +815 -0
  3. package/compiler/bundler.js +86 -0
  4. package/compiler/cli.js +843 -0
  5. package/compiler/dependency-detector.js +173 -0
  6. package/compiler/formatter.js +170 -0
  7. package/compiler/generator.js +2032 -0
  8. package/compiler/lexer.js +413 -0
  9. package/compiler/parser.js +2077 -0
  10. package/compiler/version.js +6 -0
  11. package/docs/PLINJS_SPEC.md +1051 -0
  12. package/docs/index.html +2287 -0
  13. package/docs/logo.jpg +0 -0
  14. package/docs/website/index.html +1500 -0
  15. package/docs/website/script.js +197 -0
  16. package/docs/website/style.css +1117 -0
  17. package/examples/arrays.pln +13 -0
  18. package/examples/cache-and-jobs.pln +29 -0
  19. package/examples/database.pln +41 -0
  20. package/examples/day2.pln +7 -0
  21. package/examples/day3.pln +11 -0
  22. package/examples/deployment.pln +12 -0
  23. package/examples/email-send.pln +22 -0
  24. package/examples/expressions.pln +40 -0
  25. package/examples/football-backend/app.pln +90 -0
  26. package/examples/hello.pln +3 -0
  27. package/examples/id-verification/app.pln +29 -0
  28. package/examples/id-verification/make-sample-id.js +123 -0
  29. package/examples/loops.pln +17 -0
  30. package/examples/objects.pln +12 -0
  31. package/examples/rest-api-fetch.pln +94 -0
  32. package/examples/rest-api.pln +68 -0
  33. package/examples/scheduled-tasks.pln +23 -0
  34. package/examples/server.pln +25 -0
  35. package/examples/start.pln +2 -0
  36. package/examples/stdlib.pln +41 -0
  37. package/examples/telegram-bot.pln +42 -0
  38. package/examples/web-app.pln +20 -0
  39. package/examples/websocket-server.pln +27 -0
  40. package/examples/whatsapp-bot/pairing.pln +17 -0
  41. package/examples/whatsapp-bot/qr.pln +8 -0
  42. package/package.json +47 -0
package/README.md ADDED
@@ -0,0 +1,815 @@
1
+ # PlainScript
2
+
3
+ <p align="center">
4
+ <img src="docs/logo.jpg" alt="PlainScript Logo" width="200" />
5
+ </p>
6
+
7
+ > "When even a simple sentence can be code."
8
+ > Don't forget to star the repo
9
+
10
+ PlainScript is an Intent-Oriented Programming Language (IOPL). You describe **what** you want; the compiler decides **how** to implement it in JavaScript.
11
+
12
+ **Current version:** v0.1.7 — the `plainscript` npm package with a TypeScript-style production build (`plainscript build` → `dist/`, source names preserved).
13
+
14
+ ---
15
+
16
+ ## Quick start
17
+
18
+ ```bash
19
+ npx plainscript new myapp # scaffolds src/app.pln and package.json
20
+ cd myapp
21
+ npm install # installs plainscript as a devDependency plus runtime packages
22
+ npm run build # compiles src/ -> dist/ (plainscript build)
23
+ node dist/app.js # or: npm start
24
+ ```
25
+
26
+ Adding PlainScript to an existing project:
27
+
28
+ ```bash
29
+ npm install --save-dev plainscript
30
+ # start writing src/*.pln files — plainscript build auto-discovers them
31
+ ```
32
+
33
+ No global install is needed anywhere — everything runs through npm scripts
34
+ and `npx`.
35
+
36
+ ---
37
+
38
+ ## CLI
39
+
40
+ ```
41
+ plainscript run <file.pln> Install missing dependencies, compile and execute
42
+ (executes from a scratch dir — nothing is written
43
+ into your project)
44
+ plainscript build [file.pln] Compile to dist/. With no argument, builds every
45
+ .pln file under the source root, preserving names
46
+ and folder structure
47
+ plainscript check <file.pln> Check syntax only (no output, no execution)
48
+ plainscript fmt <file.pln> Format a PlainScript file in-place
49
+ plainscript new [name] Create a new PlainScript project (npm-ready)
50
+ plainscript install Install dependencies detected in the project's sources
51
+ plainscript start Build src/app.pln and run its dist/ output
52
+ plainscript doctor Check the PlainScript project environment
53
+ plainscript add <package> Install a package into the project
54
+ plainscript remove <package> Uninstall a package from the project
55
+ plainscript update Update all installed npm packages
56
+ plainscript version Print the compiler version
57
+ plainscript help Print help text
58
+ ```
59
+
60
+ ---
61
+
62
+ ## Building and configuration
63
+
64
+ `plainscript build` is a deterministic production build, TypeScript-style but for
65
+ `.pln` sources — **zero configuration required**:
66
+
67
+ - `plainscript build` (no argument) discovers every `.pln` file under `src/` and
68
+ compiles each to `dist/` **preserving source file names and folder structure**:
69
+ `src/messi.pln` → `dist/messi.js`,
70
+ `src/helpers/math.pln` → `dist/helpers/math.js`.
71
+ - `plainscript build <file.pln>` compiles a single file into `dist/`.
72
+ - Imports are bundled into each output, so every file in `dist/` runs
73
+ standalone under Node.
74
+ - Rebuilds are byte-identical — safe to commit, diff, and cache.
75
+
76
+ Source discovery skips `node_modules`, hidden directories, and the output
77
+ directory itself. When no `src/` directory exists, the project root is scanned
78
+ instead.
79
+
80
+ ### Optional `plainscript.config.json`
81
+
82
+ For projects that need custom output or source directories, add a
83
+ `plainscript.config.json` with a `compilerOptions` block (like `tsconfig.json`):
84
+
85
+ ```json
86
+ {
87
+ "compilerOptions": {
88
+ "outDir": "./build",
89
+ "rootDir": "./lib",
90
+ "exclude": ["vendor"]
91
+ }
92
+ }
93
+ ```
94
+
95
+ | Key | Default | Meaning |
96
+ |-------------|----------------------------------|----------------------------------------------|
97
+ | `outDir` | `"dist"` | Build output directory |
98
+ | `rootDir` | `"src"` if it exists, else `"."` | Root that `plainscript build` scans for sources |
99
+ | `exclude` | `["node_modules"]` | Directories to skip during source discovery |
100
+
101
+ ### Publishing a library written in PlainScript
102
+
103
+ ```json
104
+ {
105
+ "name": "my-plainscript-library",
106
+ "main": "dist/index.js",
107
+ "scripts": {
108
+ "build": "plainscript build",
109
+ "prepare": "plainscript build"
110
+ },
111
+ "devDependencies": { "plainscript": "^0.1.7" }
112
+ }
113
+ ```
114
+
115
+ `src/index.pln` builds to `dist/index.js`; consumers install and `require()`
116
+ it like any Node package. There is no PlainScript-specific registry or format —
117
+ standard `package.json` semantics apply.
118
+
119
+ ---
120
+
121
+ ## Language features
122
+
123
+ ### Variables
124
+
125
+ ```plainscript
126
+ remember name as "Ayokunle"
127
+ remember age as 16
128
+ age becomes 17
129
+ ```
130
+
131
+ ### String Templates
132
+
133
+ Backtick-delimited strings preserve whitespace and support `${expression}` interpolation:
134
+
135
+ ```plainscript
136
+ remember name as "World"
137
+ remember greeting as `Hello ${name}!`
138
+ show greeting
139
+
140
+ remember email as `Dear ${customer},
141
+
142
+ Thank you for your order #${orderId}.
143
+
144
+ Best regards,
145
+ The Team`
146
+ ```
147
+
148
+ Interpolation compiles directly to JavaScript template literals — it is not evaluated at compile time. Literal dollar signs without `{` are preserved as-is.
149
+
150
+ ### Conditions
151
+
152
+ ```plainscript
153
+ if age is at least 18
154
+ show "Adult"
155
+ otherwise
156
+ show "Teenager"
157
+ done
158
+
159
+ if name contains "PlainScript"
160
+ show "Found it"
161
+ done
162
+
163
+ if score between 90 and 100
164
+ show "A grade"
165
+ done
166
+ ```
167
+
168
+ All comparison operators:
169
+
170
+ | PlainScript | JavaScript |
171
+ |------------------------|--------------------|
172
+ | `is` / `is equal to` | `===` |
173
+ | `is not` | `!==` |
174
+ | `is greater than` / `is above` | `>` |
175
+ | `is less than` / `is below` | `<` |
176
+ | `is at least` | `>=` |
177
+ | `is at most` | `<=` |
178
+ | `is empty` | `.length === 0` |
179
+ | `is not empty` | `.length > 0` |
180
+ | `contains "x"` | `.includes("x")` |
181
+ | `starts with "x"` | `.startsWith("x")` |
182
+ | `ends with "x"` | `.endsWith("x")` |
183
+ | `between A and B` | `>= A && <= B` |
184
+
185
+ ### Functions
186
+
187
+ ```plainscript
188
+ make add(a, b)
189
+ give a + b
190
+ done
191
+ show add(5, 7)
192
+ ```
193
+
194
+ ### Arrays & Objects
195
+
196
+ ```plainscript
197
+ remember players as ["Haaland", "Foden", "Rodri"]
198
+ show players[0]
199
+ players[1] becomes "Palmer"
200
+
201
+ remember user as
202
+ name is "Ayokunle"
203
+ age is 17
204
+ done
205
+ show user.name
206
+ ```
207
+
208
+ ### Loops
209
+
210
+ ```plainscript
211
+ for each player in players
212
+ show player
213
+ done
214
+
215
+ for every item in basket // alias for "for each"
216
+ show item
217
+ done
218
+
219
+ while age is less than 18
220
+ age becomes age + 1
221
+ done
222
+ ```
223
+
224
+ ### PlainScript Expressions
225
+
226
+ Collections, properties, and files read like sentences.
227
+
228
+ **Items**
229
+
230
+ ```plainscript
231
+ remember players as ["Haaland", "Foden", "Rodri"]
232
+
233
+ show first player from players // players[0]
234
+ show last player from players // players[players.length - 1]
235
+ show player two from players // players[1]
236
+ first player from players becomes "Haaland" // players[0] = "Haaland"
237
+ ```
238
+
239
+ Number words from `one` to `twenty` map to one-based positions: `player one` is the first item.
240
+
241
+ **Collections**
242
+
243
+ ```plainscript
244
+ show players length // players.length
245
+ add("Palmer" to players) // players.push("Palmer")
246
+ remove("Rodri" from players) // players.splice(players.indexOf("Rodri"), 1)
247
+
248
+ if players contains "Foden" // players.includes("Foden")
249
+ show "Found"
250
+ done
251
+ ```
252
+
253
+ **Properties**
254
+
255
+ ```plainscript
256
+ show name of user // user.name
257
+ show city of address of customer // customer.address.city
258
+ name of user becomes "Ayo" // user.name = "Ayo"
259
+ ```
260
+
261
+ `of` chains right-to-left: `city of address of customer` reads the city of the address of the customer.
262
+
263
+ **Files**
264
+
265
+ ```plainscript
266
+ remember data as read("users.txt") // fs.readFileSync("users.txt", 'utf8')
267
+ write(data to "users.txt") // fs.writeFileSync(data, "users.txt", 'utf8')
268
+ ```
269
+
270
+ The older `readFile()` / `writeFile()` forms still work and are unchanged.
271
+
272
+ ### JavaScript Gateway
273
+
274
+ JavaScript blocks run raw JavaScript with full async support:
275
+
276
+ ```plainscript
277
+ remember response as javascript
278
+ const res = await fetch("https://api.example.com")
279
+ const data = await res.json()
280
+ return data
281
+ done
282
+ show response
283
+ ```
284
+
285
+ `ask` reads a line of input from the terminal:
286
+
287
+ ```plainscript
288
+ ask "What is your name?" as name
289
+ show "Hello, " + name
290
+ ```
291
+
292
+ Any npm package can be declared with `use`:
293
+
294
+ ```plainscript
295
+ use axios
296
+ use node-fetch
297
+ use @scope/package-name
298
+ ```
299
+
300
+ ---
301
+
302
+ ## Backend Services
303
+
304
+ Everything below is compiled by the deterministic compiler — no rules, no AI,
305
+ no hidden codegen.
306
+
307
+ ### Portable databases (SQLite native or WebAssembly)
308
+
309
+ ```plainscript
310
+ database "app.db" // probes better-sqlite3, falls back to sql.js
311
+ ```
312
+
313
+ `plainscript install` verifies that `better-sqlite3` actually loads; if the native
314
+ module cannot be used, PlainScript warns and continues on the pure-JavaScript
315
+ WebAssembly engine (`sql.js`) — the same program runs unchanged. Force an
316
+ engine explicitly:
317
+
318
+ ```plainscript
319
+ database "app.db" using "native" // hard requirement: better-sqlite3
320
+ database "app.db" using "wasm" // hard requirement: sql.js
321
+ ```
322
+
323
+ The WebAssembly engine persists the whole database to disk after every write,
324
+ so data survives restarts either way.
325
+
326
+ ### HTTP client
327
+
328
+ ```plainscript
329
+ remember r as get "https://api.example.com/users"
330
+ if ok of r
331
+ show status of r
332
+ show data of r
333
+ done
334
+
335
+ remember created as post url with body
336
+ headers { accept: "application/json" }
337
+ timeout 5000
338
+ ```
339
+
340
+ Methods: `get`, `post … with <body>`, `put`, `patch`, `delete "<url>"`.
341
+ Responses are records: `ok`, `status`, `headers`, `data` (JSON is parsed
342
+ automatically). The default timeout is 30 seconds. `wait for fetch(...)`
343
+ awaits raw promises when you need it.
344
+
345
+ ### Passwords and tokens (built-in auth)
346
+
347
+ ```plainscript
348
+ remember hash as hashPassword("correct horse")
349
+ if checkPassword(password of body of request, hash)
350
+ remember token as createToken(user, env("TOKEN_SECRET"), 3600)
351
+ done
352
+
353
+ remember payload as readToken(token, env("TOKEN_SECRET"))
354
+ ```
355
+
356
+ `hashPassword`/`checkPassword` use scrypt; tokens are HMAC-signed with an
357
+ expiry and fail closed on tampering or timeout.
358
+
359
+ ### Sessions
360
+
361
+ ```plainscript
362
+ web app
363
+ enable sessions "a-long-random-secret"
364
+
365
+ route post "/login"
366
+ user of session of request becomes username of body of request
367
+ reply "welcome"
368
+ done
369
+
370
+ route get "/me"
371
+ reply user of session of request
372
+ done
373
+
374
+ route post "/logout"
375
+ destroy session
376
+ reply "bye"
377
+ done
378
+ ```
379
+
380
+ Sessions ride an HMAC-signed `HttpOnly` cookie (`plainscript.sid`). The store is
381
+ in-memory: restarting the server signs everyone out.
382
+
383
+ ### File uploads
384
+
385
+ ```plainscript
386
+ accept uploads limit "5 MB" allow ["image/png", "image/jpeg"] folder "uploads"
387
+
388
+ route post "/scan"
389
+ remember file as upload("doc")
390
+ ocr path of file as text
391
+ reply "scanned: " + text
392
+ done
393
+ ```
394
+
395
+ Files arrive as records with `name`, `type`, `size`, `data` (buffer) and
396
+ `path` (string, when a folder is set). Oversized files get HTTP 413, wrong
397
+ types 415. `uploads("docs")` returns every file under a field name.
398
+
399
+ ### Cookies
400
+
401
+ ```plainscript
402
+ set cookie "theme" to "dark" expires in 7 days
403
+ show cookie("theme")
404
+ clear cookie "theme"
405
+ ```
406
+
407
+ ### Rate limiting
408
+
409
+ ```plainscript
410
+ rate limit 100 requests per minute
411
+ ```
412
+
413
+ Sliding window per client IP; the quota-exceeded response is HTTP 429.
414
+
415
+ ### Google OAuth
416
+
417
+ ```plainscript
418
+ google oauth
419
+ id is env("GOOGLE_ID")
420
+ secret is env("GOOGLE_SECRET")
421
+ callback is "https://myapp.dev/auth/google/callback"
422
+ landing is "/dashboard"
423
+ done
424
+ ```
425
+
426
+ Registers `/auth/google` (redirect) and `/auth/google/callback`
427
+ (code-for-token exchange + profile fetch); after login the session holds the
428
+ user and the browser lands on `landing`.
429
+
430
+ ### Custom 404
431
+
432
+ ```plainscript
433
+ when nothing matches
434
+ status 404
435
+ reply json
436
+ error is "No such road"
437
+ done
438
+ done
439
+ ```
440
+
441
+ ### Error handling and retries
442
+
443
+ ```plainscript
444
+ try
445
+ remember data as jsonDecode(raw)
446
+ recover as err
447
+ show "bad json: " + message of err
448
+ done
449
+
450
+ retry 3 times every 5 seconds
451
+ wait for fetch("https://flaky.api")
452
+ done
453
+ ```
454
+
455
+ ---
456
+
457
+ ## Runtime Standard Library
458
+
459
+ No imports needed. These functions are built into the compiler:
460
+
461
+ | PlainScript | Description |
462
+ |--------------------------|------------------------------------|
463
+ | `print(x)` | Print a value (`console.log`) |
464
+ | `readFile("path")` | Read a file as UTF-8 text |
465
+ | `writeFile("path", data)` | Write text to a file |
466
+ | `read("path")` | Read a file as UTF-8 text |
467
+ | `fileExists("path")` | Check if a file exists |
468
+ | `sleep(ms)` | Sleep synchronously |
469
+ | `time()` | Current Unix timestamp (`Date.now()`) |
470
+ | `date()` | ISO date string |
471
+ | `jsonEncode(value)` | `JSON.stringify` |
472
+ | `jsonDecode(string)` | `JSON.parse` |
473
+ | `env("KEY")` | Read environment variable |
474
+ | `exit(code)` | Exit the process |
475
+ | `uuid()` | Generate a UUID v4 |
476
+ | `length(x)` | Length of array/string |
477
+ | `uppercase(x)` | Convert to uppercase |
478
+ | `lowercase(x)` | Convert to lowercase |
479
+ | `random()` | Random number 0–1 |
480
+ | `round(x)` | Round to nearest integer |
481
+
482
+ ---
483
+
484
+ ## Web Apps
485
+
486
+ ```plainscript
487
+ web app
488
+
489
+ route "/"
490
+ reply "Hello from PlainScript!"
491
+ done
492
+
493
+ route "/api/status"
494
+ reply json
495
+ status is "ok"
496
+ version is "2.0"
497
+ done
498
+ done
499
+
500
+ start 3000
501
+ ```
502
+
503
+ ---
504
+
505
+ ## SQLite Database
506
+
507
+ ```plainscript
508
+ database "app.db"
509
+
510
+ execute
511
+ CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)
512
+ done
513
+
514
+ insert
515
+ INSERT INTO users (name) VALUES ('Alice')
516
+ done
517
+
518
+ remember rows as query
519
+ SELECT * FROM users
520
+ done
521
+ ```
522
+
523
+ ---
524
+
525
+ ## Backend Capabilities
526
+
527
+ Everything a backend needs, as first-class deterministic language features —
528
+ no rules, no AI, no hidden codegen.
529
+
530
+ ### HTTP routing
531
+
532
+ ```plainscript
533
+ web app
534
+ allow cors
535
+
536
+ group "/api"
537
+
538
+ route get "/users"
539
+ remember users as query
540
+ SELECT * FROM users
541
+ done
542
+ reply users
543
+ done
544
+
545
+ route post "/users"
546
+ remember missing as validate(body of request, ["name", "email"])
547
+ if length(missing) is greater than 0
548
+ status 400
549
+ reply missing
550
+ otherwise
551
+ reply "created"
552
+ done
553
+ done
554
+
555
+ done
556
+
557
+ start env("PORT")
558
+ ```
559
+
560
+ `param("id")`, `query("page")` and `header("x-token")` read request data;
561
+ `group` composes path prefixes; `status <n>` sets the response code.
562
+
563
+ ### Databases with parameters and transactions
564
+
565
+ ```plainscript
566
+ database "app.db" // or: postgres env("DATABASE_URL")
567
+
568
+ transaction
569
+ insert
570
+ INSERT INTO users (name) VALUES ({who})
571
+ done
572
+ done
573
+ ```
574
+
575
+ Placeholders `{likeThis}` bind to PlainScript variables. `postgres "..."` switches
576
+ every SQL statement to node-postgres pool queries (`$n`, awaited).
577
+
578
+ ### Email
579
+
580
+ ```plainscript
581
+ mail transport
582
+ host is "smtp.gmail.com"
583
+ port is 587
584
+ user is env("EMAIL_USER")
585
+ pass is env("EMAIL_PASS")
586
+ done
587
+
588
+ send mail
589
+ from is "hello@plainscript.dev"
590
+ to is "you@example.com"
591
+ subject is "Hello from PlainScript"
592
+ text is "Sent from a PlainScript program."
593
+ done
594
+ ```
595
+
596
+ ### Cron and background jobs
597
+
598
+ ```plainscript
599
+ every 5 minutes
600
+ show "heartbeat"
601
+ done
602
+
603
+ schedule "0 2 * * *"
604
+ show "nightly cleanup"
605
+ done
606
+
607
+ run background resizeImage("photo.png")
608
+ ```
609
+
610
+ ### WebSocket servers
611
+
612
+ ```plainscript
613
+ websocket server on 8080
614
+ when socket connects
615
+ send socket "Welcome!"
616
+ done
617
+ when socket sends message
618
+ broadcast message
619
+ done
620
+ done
621
+ ```
622
+
623
+ ### Cache (Redis)
624
+
625
+ ```plainscript
626
+ cache env("REDIS_URL")
627
+ remember token as cacheGet("token")
628
+ cacheSet("greeting", "hi", 60)
629
+ cacheDelete("greeting")
630
+ ```
631
+
632
+ ---
633
+
634
+ ## Multi-file projects
635
+
636
+ ```plainscript
637
+ import "./math.pln"
638
+ import "./utils.pln"
639
+
640
+ show PI
641
+
642
+ show double(5)
643
+ ```
644
+
645
+ Imports are bundled per entry: `plainscript build` gives every source file its own
646
+ standalone output under `dist/`, with imported code inlined.
647
+
648
+ ---
649
+
650
+ ## Express server
651
+
652
+ ```plainscript
653
+ use express
654
+
655
+ remember app as express()
656
+
657
+ serve folder "public"
658
+
659
+ when someone visits "/"
660
+ reply "Hello from PlainScript!"
661
+ done
662
+
663
+ when someone visits "/api/status"
664
+ reply json
665
+ status is "ok"
666
+ version is "0.3"
667
+ done
668
+ done
669
+
670
+ listen on 3000
671
+ show "Server running at http://localhost:3000"
672
+ done
673
+ ```
674
+
675
+ ---
676
+
677
+ ## WhatsApp Bots
678
+
679
+ Full WhatsApp connectivity through Baileys — the implementation package is
680
+ installed automatically and never appears in your source:
681
+
682
+ ```plainscript
683
+ whatsapp bot
684
+ auth "session" // credential folder, persists
685
+ // across restarts
686
+ login qr // or: login pairing "2348012345678"
687
+
688
+ on message
689
+ log message // print the normalized record
690
+
691
+ if message.text is "/start"
692
+ reply "Welcome!"
693
+ done
694
+
695
+ if message.text is "/help"
696
+ reply `Available commands:
697
+ /start /help`
698
+ done
699
+ done
700
+ done
701
+ ```
702
+
703
+ - `login qr` prints a scannable QR code; `login pairing "<number>"` prints an
704
+ enter-on-phone code instead. Pairing numbers are validated at compile time
705
+ (digits only after normalization, 8–15).
706
+ - `login pairing` also accepts any value — prompt for the number
707
+ at runtime instead of hard-coding it:
708
+
709
+ ```plainscript
710
+ ask "WhatsApp number: " as phone
711
+
712
+ whatsapp bot
713
+ auth "session"
714
+ login pairing phone
715
+ done
716
+ ```
717
+
718
+ - Inside `on message`, `message` holds `{ text, chat, sender, name, id,
719
+ time, isGroup }`; `reply` answers the current chat.
720
+ - The bot ignores its own messages and status broadcasts and keeps working in
721
+ groups; transient disconnects reconnect after 3 seconds.
722
+
723
+ See `examples/whatsapp-bot/` for ready-to-link programs.
724
+
725
+ ---
726
+
727
+ ## Project management
728
+
729
+ ```bash
730
+ plainscript install # Install all detected dependencies
731
+ plainscript add express # Add a package
732
+ plainscript remove express # Remove a package
733
+ plainscript update # Update all packages
734
+ plainscript start # Build src/app.pln and run its dist/ output
735
+ plainscript doctor # Check project environment
736
+ ```
737
+
738
+ ---
739
+
740
+ ## Supported packages
741
+
742
+ | PlainScript | Compiles to |
743
+ |---------------------------|--------------------------------------|
744
+ | `use express` | `const express = require('express');` |
745
+ | `use sqlite` | `const Database = require('better-sqlite3');` |
746
+ | `use fs` | `const fs = require('fs');` |
747
+ | `use path` | `const path = require('path');` |
748
+
749
+ Any npm package can be used, including hyphenated names like `node-fetch` and
750
+ scoped packages like `@scope/package-name`.
751
+
752
+ ---
753
+
754
+ ## Running the tests
755
+
756
+ ```bash
757
+ npm test
758
+ ```
759
+
760
+ ---
761
+
762
+ ## Project structure
763
+
764
+ ```
765
+ plainscript/
766
+ ├── compiler/
767
+ │ ├── lexer.js — tokenises PlainScript source into tokens
768
+ │ ├── parser.js — builds an AST from tokens
769
+ │ ├── generator.js — generates JavaScript from the AST
770
+ │ ├── bundler.js — resolves imports and bundles files
771
+ │ ├── formatter.js — normalises PlainScript source style
772
+ │ ├── dependency-detector.js— detects npm packages from source
773
+ │ ├── version.js — single compiler version constant
774
+ │ └── cli.js — command-line entry point
775
+ │
776
+ ├── examples/
777
+ │ ├── hello.pln
778
+ │ ├── day2.pln
779
+ │ ├── day3.pln
780
+ │ ├── arrays.pln
781
+ │ ├── objects.pln
782
+ │ ├── loops.pln
783
+ │ ├── expressions.pln
784
+ │ ├── stdlib.pln
785
+ │ ├── server.pln
786
+ │ ├── web-app.pln
787
+ │ ├── start.pln
788
+ │ ├── database.pln
789
+ │ ├── deployment.pln
790
+ │ ├── football-backend/ — acceptance example (SQLite + auth + sessions)
791
+ │ │ └── app.pln
792
+ │ ├── id-verification/ — acceptance example (uploads + OCR matching)
793
+ │ │ ├── app.pln
794
+ │ │ └── make-sample-id.js
795
+ │ └── whatsapp-bot/ — WhatsApp bots (QR and pairing linking)
796
+ │ ├── qr.pln
797
+ │ └── pairing.pln
798
+ │
799
+ ├── tests/
800
+ │ ├── compiler.test.js — language, CLI and formatter coverage
801
+ │ ├── build.test.js — build model, config and packaging coverage
802
+ │ ├── backend.test.js — web/database/email/cache runtime tests
803
+ │ ├── telegram.test.js — Telegram bot runtime tests
804
+ │ ├── ocr.test.js — OCR statement tests
805
+ │ ├── runtime.test.js — uploads, database and bot feature suite
806
+ │ ├── whatsapp.test.js — WhatsApp bot runtime tests
807
+ │ └── acceptance.test.js — boots the example projects over live HTTP
808
+ │
809
+ ├── docs/
810
+ │ ├── PlainScript_SPEC.md
811
+ │ └── index.html
812
+ │
813
+ ├── package.json
814
+ └── README.md
815
+ ```