fastscript 1.0.0 → 3.0.0

package/README.md

@@ -1,117 +1,649 @@
 # FastScript
 
-FastScript is a JavaScript-first full-stack framework focused on three things:
+FastScript is a proprietary, source-available JavaScript-first full-stack runtime built around a first-class `.fs` file format.
 
-- Simpler than heavy framework stacks
-- Faster build and runtime pipeline
-- Compatible with existing JavaScript ecosystem
-- `.fs` first, `.js` always supported
+It is designed to feel easier to read than heavyweight stack combinations while staying compatible with the JavaScript ecosystem developers already use.
 
-## Commands
+- Write normal JavaScript or TypeScript in `.fs`
+- Write pages, APIs, middleware, jobs, and database workflows in `.fs`
+- Keep compatibility with normal `.js` packages and modules
+- Treat FastScript-specific syntax as optional sugar, not a requirement
+- Compile to optimized JavaScript for production deployment
+- Deploy the same app to Node, Vercel, or Cloudflare
+- Run one quality gate for formatting, linting, typecheck, tests, smoke checks, benchmarks, and interop
+- Build on the same language/runtime foundation that powers the future FastScript AI coding products
+
+FastScript v3 is built for product teams that want a simpler, faster full-stack pipeline without surrendering compatibility with the ground-level JavaScript platform.
+
+The v3 product contract is simple:
+
+- `.fs` is a universal JS/TS container for the FastScript runtime
+- FastScript-specific syntax is optional sugar
+- valid JS/TS failures in `.fs` are FastScript compatibility bugs
+- the speed story is earned by the runtime/compiler/toolchain and backed by release proof artifacts
+
+## What FastScript Is
+
+FastScript combines:
+
+1. A JS/TS-compatible source container: `.fs`
+2. A compiler and CLI
+3. A full-stack app runtime
+4. A deployment pipeline for multiple targets
+5. A bridge back to standard JavaScript and TypeScript export paths
+
+That means a single project can contain:
+
+- UI pages
+- API handlers
+- middleware
+- database migrations
+- seed scripts
+- jobs and workers
+- deploy adapters
+
+## Core Positioning
+
+FastScript is built to be:
+
+- Simpler than stacking TypeScript + framework + glue code everywhere
+- Faster to build and ship than heavier pipeline combinations
+- Compatible with existing JavaScript libraries
+- Friendly to AI-assisted generation because the language surface is smaller and more regular
+- Easy to migrate into and easy to export back out
+
+## Current Measured Numbers
+
+These are the real measured numbers from the current repo benchmark report:
+
+- Build time: `702.98ms`
+- JS first-load gzip: `2.71KB`
+- Routes in benchmark app: `16`
+- API routes in benchmark app: `5`
+- Interop matrix: `13/13` passing
+- Current website deploy target: Node, Vercel, and Cloudflare adapters supported
+
+See:
+
+- `benchmarks/latest-report.md`
+- `benchmarks/suite-latest.json`
+- `benchmarks/interop-latest.json`
+- `docs/PROOF_PACK.md`
+
+## Why Teams Pick FastScript
+
+- Smaller client payloads than heavier framework baselines
+- Faster build loops and stricter release gates in one toolchain
+- One runtime-native source container for pages, APIs, jobs, and middleware
+- Package compatibility without giving up a proprietary language/runtime moat
+- A direct path into the next FastScript AI assistant stack
+
+## Install
+
+### Option 1: npm install
+
+```bash
+npm install -g fastscript
+fastscript --help
+```
+
+The published npm package is generated as a self-contained release bundle, so the CLI works without a second private npm package.
+
+### Option 2: local repo workflow
+
+```bash
+git clone https://github.com/lordolami/fastscript.git
+cd fastscript
+npm install
+```
+
+### Option 3: global CLI link for daily use
 
 ```bash
+git clone https://github.com/lordolami/fastscript.git
+cd fastscript
 npm install
+npm link
+fastscript --help
+```
+
+This gives you a global `fastscript` command backed by your local clone.
+
+The source repos remain split for development, but npm users get a clean self-contained public package.
+
+To use the CLI directly during development:
+
+```bash
+node ./src/cli.mjs --help
+```
+
+If you publish or link the package locally, the command is:
+
+```bash
+fastscript
+```
+
+## Quick Start
+
+### Create a project
+
+```bash
 npm run create
+```
+
+Or use one of the included templates:
+
+```bash
+npm run create:fullstack
+npm run create:startup-mvp
+```
+
+### Run locally
+
+```bash
+npm run dev
+```
+
+### Link the CLI globally from your clone
+
+```bash
+npm link
+fastscript create my-app
+```
+
+### Build for production
+
+```bash
+npm run build
+```
+
+### Start the production build
+
+```bash
+npm run start
+```
+
+### Run the full quality gate
+
+```bash
+npm run qa:all
+```
+
+## The `.fs` Language At A Glance
+
+FastScript keeps normal JavaScript module structure and adds a few core forms:
+
+- `fn` for functions
+- `state` for named stateful declarations
+- `~name = ...` for lightweight reactive-style declarations
+- type syntax that can be stripped at compile time
+- file conventions for pages, APIs, and runtime hooks
+
+### Example: basic page
+
+```fs
+export default fn Page() {
+  state title = "FastScript"
+  ~subtitle = "Write once. Ship anywhere."
+
+  return `
+    <section>
+      <h1>${title}</h1>
+      <p>${subtitle}</p>
+    </section>
+  `
+}
+```
+
+### Example: load data for a page
+
+```fs
+export async fn load(ctx) {
+  const user = await ctx.db.get("users", ctx.params.id)
+  if (!user) return { notFound: true }
+  return { user }
+}
+
+export default fn Page({ user }) {
+  return `<h1>${user.name}</h1>`
+}
+```
+
+### Example: API route
+
+```fs
+export const schemas = {
+  POST: { sku: "string", qty: "int" }
+}
+
+export async fn POST(ctx) {
+  const body = await ctx.input.validateBody(schemas.POST)
+  const order = { id: Date.now().toString(36), ...body }
+  ctx.db.collection("orders").set(order.id, order)
+  ctx.queue.enqueue("send-order-email", { orderId: order.id })
+  return ctx.helpers.json({ ok: true, order })
+}
+```
+
+### Example: middleware
+
+```fs
+export async fn middleware(ctx, next) {
+  ctx.state.requestStartedAt = Date.now()
+
+  if (ctx.url.pathname.startsWith("/private") && !ctx.session?.user) {
+    return ctx.helpers.redirect("/")
+  }
+
+  return next()
+}
+```
+
+### Example: hydration hook for client behavior
+
+```fs
+export function hydrate({ root }) {
+  const button = root.querySelector("[data-action]")
+  if (!button) return
+
+  button.addEventListener("click", () => {
+    console.log("hydrated")
+  })
+}
+```
+
+## Page Contract
+
+A FastScript page can export any of the following:
+
+- `export default fn Page(...)` or `export default function Page(...)`
+- `export async fn load(ctx)` for server-side data loading
+- `export function hydrate({ root, ...ctx })` for client behavior
+- HTTP method handlers like `POST`, `PUT`, `PATCH`, `DELETE`
+
+### Minimal page
+
+```fs
+export default fn Page() {
+  return `<h1>Hello</h1>`
+}
+```
+
+### Page with loader
+
+```fs
+export async fn load(ctx) {
+  return { now: new Date().toISOString() }
+}
+
+export default fn Page({ now }) {
+  return `<p>${now}</p>`
+}
+```
+
+## Routing
+
+FastScript uses file-based routing under `app/pages`.
+
+### Route examples
+
+- `app/pages/index.fs` -> `/`
+- `app/pages/blog/index.fs` -> `/blog`
+- `app/pages/blog/[slug].fs` -> `/blog/:slug`
+- `app/pages/docs/[...slug].fs` -> `/docs/:slug*`
+- `app/pages/[[...slug]].fs` -> optional catch-all
+- `app/pages/blog/[id:int].fs` -> typed param route
+- `app/pages/404.fs` -> not-found page
+- `app/pages/_layout.fs` -> global layout wrapper
+
+## Full-Stack Surface Area
+
+FastScript currently includes first-party support for:
+
+- pages
+- layouts
+- API routes
+- middleware
+- auth/session flows
+- database migrations
+- database seed scripts
+- storage and upload handlers
+- jobs and worker runtime
+- deploy targets
+- benchmark and interop reporting
+- docs indexing and API reference generation
+
+## Interop Story
+
+FastScript is designed to sit on top of the JavaScript ecosystem, not replace it with an isolated wall.
+
+### What works
+
+- normal `.js` dependencies
+- ESM/CJS compatibility checks
+- export from `.fs` to `.js`
+- export from `.fs` to `.ts`
+- migration tooling from page-based JS/TS apps into `.fs`
+
+### Why that matters
+
+Developers should be able to:
+
+1. migrate into FastScript without rewriting the whole world
+2. use existing libraries
+3. export back out when needed
+4. keep real production optionality
+
+## Commands
+
+### Main app lifecycle
+
+```bash
 npm run dev
 npm run start
 npm run build
+npm run build:ssg
+npm run create
 npm run check
+npm run validate
+```
+
+### Language and migration
+
+```bash
 npm run migrate
-npm run bench
+npm run convert
+npm run migrate:rollback
+npm run manifest
+npm run wizard:migrate
 npm run export:js
 npm run export:ts
 npm run compat
-npm run validate
+npm run typecheck
+npm run typecheck:pass
+npm run lint:fs
+npm run lint:fs:pass
+npm run diagnostics
+npm run permissions
+npm run format
+npm run format:check
+```
+
+`migrate` now runs strict compatibility-first conversion (rename-only + import extension rewrites + manifest/validation/fidelity reports).  
+Example: `npm run migrate -- app --dry-run`  
+Full proof mode: `npm run migrate -- app --fidelity-level full --fail-on-unproven-fidelity`
+
+Latest trust artifacts are written to `.fastscript/conversion/latest`:
+`conversion-manifest.json`, `diff-preview.json`, `validation-report.json`, `fidelity-report.json`.
+
+Authored `.fs` now accepts normal JS/TS/JSX/TSX-style code directly. Proof artifacts for the current parity contract are written to `.fastscript/proofs/js-ts-syntax-proof.json` and `.fastscript/proofs/fs-parity-matrix.json`.
+
+### Database and data
+
+```bash
 npm run db:migrate
 npm run db:seed
+npm run db:rollback
+```
+
+### Deploy and runtime
+
+```bash
+npm run deploy:node
+npm run deploy:vercel
+npm run deploy:cloudflare
+npm run worker
+npm run worker:replay-dead-letter
+```
+
+### Quality and testing
+
+```bash
 npm run smoke:dev
 npm run smoke:start
 npm run test:core
-npm run test:language-spec
-npm run test:parser-fuzz
-npm run test:normalizer-stress
-npm run test:determinism
-npm run test:runtime-contract
-npm run bench:language
-npm run bench:report
+npm run test:conformance
+npm run test:plugins
+npm run test:routes
+npm run test:interop-matrix
+npm run test:vscode-language
 npm run qa:gate
 npm run qa:all
-npm run worker
-npm run deploy:node
-npm run deploy:vercel
-npm run deploy:cloudflare
+```
+
+### Benchmarks, reports, and ops
+
+```bash
+npm run bench
+npm run bench:discipline
+npm run regression
+npm run profile
+npm run trace
+npm run bench:report
+npm run benchmark:suite
+npm run interop:report
+npm run sbom:generate
+npm run proof:publish
+npm run backup:create
+npm run backup:restore
+npm run backup:verify
+npm run retention:sweep
+npm run kpi:track
+npm run deploy:zero-downtime
+```
+
+### Release and tooling
+
+```bash
 npm run release:patch
+npm run release:minor
+npm run release:major
 npm run pack:check
+npm run hooks:install
+npm run repo:lock
+npm run plugins:marketplace-sync
+npm run docs:index
+npm run docs:api-ref
+npm run style:generate
+npm run style:check
 ```
 
-- `npm run migrate`: convert `app/pages` files (`.js/.jsx/.ts/.tsx`) to `.fs`
-- `npm run bench`: enforce 3G-oriented gzip budgets on built output
-- `npm run export:js`: export `.fs` app source to plain `.js` project
-- `npm run export:ts`: export `.fs` app source to `.ts` project
-- `npm run compat`: run ESM/CJS/FS interop smoke checks
-- `npm run db:migrate`: run database migrations from `app/db/migrations`
-- `npm run db:seed`: seed database from `app/db/seed.js`
-- `npm run validate`: run full quality gate (check/build/bench/compat/db/export)
-- `npm run smoke:dev`: automated SSR/API/auth/middleware smoke test
-- `npm run smoke:start`: production `fastscript start` smoke test
-- `npm run test:core`: middleware/auth/db/migration round-trip tests
-- `npm run test:language-spec`: validates language spec API and strict diagnostics
-- `npm run test:parser-fuzz`: randomized parser/normalizer robustness sweep
-- `npm run test:normalizer-stress`: load/stress test for lenient parser pipeline
-- `npm run test:determinism`: build determinism check
-- `npm run test:runtime-contract`: route/runtime manifest contract test
-- `npm run bench:language`: writes parser/normalizer benchmark baseline
-- `npm run bench:report`: writes benchmark report to `benchmarks/latest-report.md`
-- `npm run qa:gate`: validation + full test suite for merge gating
-- `npm run qa:all`: full quality sweep in one command
-- `npm run worker`: run queue worker runtime
-- `npm run deploy:*`: generate deploy adapters for node/vercel/cloudflare
-- `npm run release:*`: semver bump + changelog append
-- `npm run pack:check`: npm publish dry-run
-
-## Additional Docs
+## Recommended Developer Flow
 
-- `docs/AI_CONTEXT_PACK_V1.md`
-- `docs/PLUGIN_API_CONTRACT.md`
-- `docs/INCIDENT_PLAYBOOK.md`
-- `docs/DEPLOY_GUIDE.md`
-- `docs/V1_TRANCHE_1_44.md`
+For normal development:
+
+```bash
+npm install
+npm run dev
+```
+
+Before shipping:
+
+```bash
+npm run qa:all
+```
+
+For deployment:
+
+```bash
+npm run deploy:cloudflare
+```
+
+Or:
+
+```bash
+npm run deploy:node
+npm run deploy:vercel
+```
 
-## Project layout
+## Project Layout
 
 ```txt
 app/
-  pages/
-    _layout.fs
-    index.fs
-    404.fs
   api/
-    hello.js
-    auth.js
+    auth.fs
+    docs-search.fs
+    hello.fs
+    upload.fs
+    webhook.fs
   db/
     migrations/
-      001_init.js
-    seed.js
+      001_init.fs
+    seed.fs
+  design/
+    class-allowlist.json
+    tokens.json
+  pages/
+    _layout.fs
+    index.fs
+    learn.fs
+    examples.fs
+    benchmarks.fs
+    roadmap.fs
+    docs/
+      index.fs
+      latest.fs
+      playground.fs
+      search.fs
+      v1/
+        index.fs
+      v1.1/
+        index.fs
+    blog/
+      index.fs
+      [slug].fs
+  env.schema.fs
   middleware.fs
   styles.css
+  styles.generated.css
+src/
+  cli.mjs
+  build.mjs
+  server-runtime.mjs
+examples/
+  fullstack/
+  startup-mvp/
+spec/
+  LANGUAGE_V1_SPEC.md
+  MASTER_TODO.md
 ```
 
-## Page contract
+## Example Projects Included
 
-- `export default function Page(ctx) { return htmlString }`
-- Optional `export async function load(ctx) { return data }`
-- Optional method actions in page files: `POST/PUT/PATCH/DELETE`
-- `.fs` supports lenient FastScript syntax such as `~state = value`
-- Optional `export function hydrate({ root, ...ctx })` for client hydration
+### `examples/fullstack`
+A production-style full-stack starter with:
 
-## Routing
+- pages
+- API route
+- migration
+- seed script
+- job handler
+- layout
+
+### `examples/startup-mvp`
+A more startup-shaped example with:
+
+- cart + checkout APIs
+- dashboard page
+- migrations
+- email job flow
+
+## Deploy Targets
+
+FastScript currently has deploy adapters for:
+
+- Node
+- Vercel
+- Cloudflare
+
+The long-term direction is one language, many targets:
+
+- web
+- server
+- mobile
+- desktop
+
+That roadmap is tracked in:
+
+- `spec/MULTI_TARGET_APP_PLAN.md`
+- `app/pages/roadmap.fs`
+
+## Documentation Map
+
+Key docs in this repo:
+
+- `spec/LANGUAGE_V1_SPEC.md`
+- `spec/STYLING_V1_SPEC.md`
+- `docs/GOVERNANCE_VERSIONING_POLICY.md`
+- `docs/LANGUAGE_V1_MIGRATION.md`
+- `docs/COMPILER_ERROR_CODES.md`
+- `docs/AI_CONTEXT_PACK_V1.md`
+- `docs/PLUGIN_API_CONTRACT.md`
+- `docs/INCIDENT_PLAYBOOK.md` (public stub; full version lives in private core)
+- `docs/DEPLOY_GUIDE.md`
+- `docs/SUPPORT_MATRIX.md`
+- `docs/RELEASE_PROCESS.md`
+- `docs/TROUBLESHOOTING.md`
+- `docs/ARCHITECTURE_OVERVIEW.md`
+- `docs/KNOWN_LIMITATIONS.md`
+- `docs/CONTRIBUTING.md`
+- `docs/OBSERVABILITY.md` (public stub; full version lives in private core)
+- `docs/RUNTIME_PERMISSIONS.md`
+- `docs/ROLLOUT_GUIDE.md` (public stub; full version lives in private core)
+- `SECURITY.md`
+
+## Protection, Licensing, and Commercial Use
+
+FastScript is being built as the core language layer for a larger AI product. Because of that, the repository is not licensed under a permissive open-source license.
+
+What that means in practice:
+
+- you can review the repository and evaluate it internally;
+- you cannot commercially use, redistribute, relicense, or build competing products on top of this code without written permission;
+- you cannot use this repository to train, fine-tune, improve, or evaluate a commercial AI product without written permission;
+- trademark rights in the FastScript name, logo, and branding are reserved.
+
+If you need commercial use, partnership, integration, or platform rights, contact:
+
+- `legal@fastscript.dev`
+
+## Contributing
+
+FastScript is evolving quickly. If you contribute:
+
+1. keep the canonical repo lock intact
+2. run `npm run qa:all`
+3. keep `.fs` and `.js` interop working
+4. avoid unnecessary ecosystem lock-in
+5. preserve the language goal: simpler, faster, still grounded in JavaScript
+
+Contribution review does not grant any right to commercially reuse the platform outside the repository license.
+
+## Public/Private Boundary
+
+This public repository is the developer-facing FastScript surface. Sensitive compiler/runtime/platform materials now live in the protected private repository `https://github.com/lordolami/fastscript-core-private`. The public repo consumes private-core modules through bridge files and tracks the boundary in `docs/PRIVATE_CORE_SPLIT.md`.
+
+## Canonical Repo
+
+Canonical repo lock:
+
+`github.com/lordolami/fastscript`
+
+The repo lock script is:
+
+```bash
+npm run repo:lock
+```
+
+## License
 
-- `app/pages/index.fs` or `index.js` -> `/`
-- `app/pages/blog/index.fs` or `index.js` -> `/blog`
-- `app/pages/blog/[slug].fs` or `[slug].js` -> `/blog/:slug`
-- `app/pages/404.fs` or `404.js` -> not found view
-- `app/pages/_layout.fs` or `_layout.js` -> global layout wrapper
+This repository is licensed under the FastScript Source-Available License v1.
 
-## Why this reset
+See:
 
-This repo was reset intentionally to rebuild from ground up around a JavaScript-first model with minimal syntax friction.
+- `LICENSE`
+- `SECURITY.md`
+- `app/pages/license.fs`
+
+
+