@alzulejos/laranja-docs 0.2.4

package/content/getting-started/how-it-works.md

@@ -0,0 +1,52 @@
+---
+title: How it works
+description: How laranja turns your code into a running app on AWS.
+order: 4
+---
+
+# How it works
+
+You write your app; laranja deploys it to your own AWS account. Two things are
+worth knowing about how it does that.
+
+## It reads your code — it never runs it
+
+laranja discovers your infrastructure by **reading** your source: your HTTP app
+and its routes, your `@Cron` / `cron()` jobs and their schedules, your
+`@Queue` / `queue()` consumers, and the env vars you wrap with `env()`. It does
+this without executing your code, so planning a deploy is always safe — nothing
+of yours runs just to figure out what to deploy.
+
+That's also why a few things must be written so laranja can see them: schedules
+use literal builders like `rate(5, "minutes")`, and `env("…")` takes a string
+literal.
+
+## It deploys into your AWS account
+
+laranja turns what it found into AWS resources — a Lambda for your app, an
+EventBridge rule per cron, an SQS queue per consumer — and deploys them with
+**your** credentials into **your** account. See
+[what gets deployed](../reference/what-gets-deployed.md) for the full mapping.
+
+- The AWS CDK toolkit is embedded, so there's nothing extra to install.
+- The first deploy to a new account/region runs a one-time **bootstrap**.
+- [`plan`](../reference/commands.md#plan) previews what a deploy would change
+  (created/changed/unchanged); [`destroy`](../reference/commands.md#destroy)
+  tears the stack down.
+- Outputs (your HTTPS URL, queue URLs) are printed when the deploy finishes.
+
+## The template is built on the server — your code stays local
+
+[`plan`](../reference/commands.md#plan) and [`deploy`](../reference/commands.md#deploy)
+synthesize the deployment template on the **laranja server**. laranja scans and
+bundles your code locally, then sends only a **description** of your
+infrastructure (the internal model plus the asset hashes of your bundles) — your
+source code and bundles never leave your machine. The returned template is then
+applied to AWS with your **own** credentials. This is why these commands need a
+`LARANJA_API_KEY` and a `projectId` (run [`laranja init`](../reference/commands.md#init)
+once to set both up).
+
+## Related
+
+- [What gets deployed](../reference/what-gets-deployed.md)
+- [Stages & environments](../guides/stages-and-environments.md)

package/content/getting-started/installation.md

@@ -0,0 +1,58 @@
+---
+title: Installation
+description: Prerequisites and how to add laranja to a project.
+order: 2
+---
+
+# Installation
+
+## Prerequisites
+
+- **Node.js 20 or newer.** Deployed Lambdas run on the Node.js 20 runtime, and
+  the CLI targets the same.
+- **A laranja account + API key.** laranja synthesizes your deployment template on
+  its server, so `plan`, `deploy`, and `eject` need an API key (created in the
+  dashboard) and a project to link to. You connect both by running
+  [`laranja init`](./quickstart.md#3-sign-in-and-configure) — see the Quickstart.
+- **An AWS account** plus credentials on the standard AWS chain — any of:
+  - `aws configure` (a shared credentials file),
+  - AWS SSO (`aws sso login`),
+  - environment variables (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN`),
+  - a named profile (set [`profile`](../reference/config-file.md) in config).
+- **A region**, from `region` in your config or the `AWS_REGION` /
+  `AWS_DEFAULT_REGION` environment variable.
+
+You do **not** need to install the AWS CDK or the AWS CLI separately — the CDK
+toolkit is embedded in laranja.
+
+## Install
+
+Add the CLI as a dev dependency:
+
+```bash
+npm install -D @alzulejos/laranja
+```
+
+If you use decorators or function markers for jobs and queues, also install:
+
+```bash
+npm install @alzulejos/laranja-decorators
+```
+
+> `@alzulejos/laranja-decorators` is a regular dependency (not dev-only) because your
+> application imports `@Cron`, `@Queue`, `rate`, etc. at runtime.
+
+## First-time AWS setup (bootstrap)
+
+The first time you deploy to a given account + region, laranja runs a one-time
+**bootstrap** that creates a small set of shared resources in _your_ account (an
+S3 asset bucket and a few IAM roles). `laranja deploy` detects this and prompts
+you before doing it — see [deploy](../reference/commands.md#deploy).
+
+## Verify
+
+```bash
+npx laranja --help
+```
+
+You're ready for the **[Quickstart](./quickstart.md)**.

package/content/getting-started/introduction.md

@@ -0,0 +1,97 @@
+---
+title: Introduction
+description: What laranja is, the problem it solves, and the principles behind it.
+order: 1
+---
+
+# Introduction
+
+laranja is a **code-first deploy tool** for Node.js apps. You write your
+application — an Express app, some scheduled jobs, some queue consumers — and
+laranja deploys it to **your own AWS account**. There is no infrastructure
+project to maintain, no YAML to write, and no cloud console to click through.
+
+> laranja supports **Express** and **NestJS** — and because your app is reduced to
+> a framework-neutral description internally, more frameworks can follow without
+> changing how you write your code.
+
+## The problem
+
+Shipping a small Node service to AWS usually means choosing between:
+
+- **A platform** (managed hosting) — fast, but you don't own the infrastructure
+  and you pay a markup to run in someone else's account.
+- **Infrastructure-as-code** (CDK / Terraform / CloudFormation) — you own
+  everything, but now you maintain a second codebase that drifts from the app it
+  describes.
+
+laranja takes a third path: **your application code _is_ the source of truth for
+the infrastructure.** A route is an HTTP endpoint. A `@Cron` method is a
+scheduled function. A `@Queue` method is an SQS consumer. laranja reads those
+facts out of your code and provisions exactly what they imply.
+
+## How it feels
+
+```ts
+// src/app.ts — mark your HTTP app, code-first
+import express from "express";
+import { http } from "@alzulejos/laranja-decorators";
+
+const app = express();
+app.get("/health", (_req, res) => res.json({ ok: true }));
+
+export default http(app);
+```
+
+Jobs and queues come in two styles — plain **functions** or **classes** with
+decorators. Use whichever you prefer:
+
+```ts tab="Function"
+// src/jobs.ts
+import { cron, rate } from "@alzulejos/laranja-decorators";
+
+export async function refreshCache() { /* ... */ }
+cron(rate(5, "minutes"), refreshCache);
+```
+
+```ts tab="Class"
+// src/jobs.ts
+import { Cron, rate } from "@alzulejos/laranja-decorators";
+
+export class Jobs {
+  @Cron(rate(5, "minutes"))
+  async refreshCache() { /* ... */ }
+}
+```
+
+```bash
+npx laranja deploy
+```
+
+You get a live HTTPS URL, an EventBridge schedule, and an SQS queue with a
+consumer — all in your own account, named deterministically.
+
+## Principles
+
+- **Code is the source of truth.** Infrastructure is _derived_ from the app, not
+  declared alongside it. There's nothing to keep in sync.
+- **Your account, your resources.** laranja deploys with your AWS credentials
+  into your account. You own every resource and can inspect it in the console.
+- **Deterministic, no magic names.** Resources are named `‹app›-‹fn›-‹stage›` —
+  predictable and greppable, with no random suffixes.
+- **Provider-neutral by design.** AWS is the first target, but laranja is built
+  so other clouds can follow without changing your app code.
+- **An escape hatch when you need it.** Outgrow the abstraction? `laranja eject`
+  hands you a real, owned CDK project (see [eject](../reference/commands.md#eject)).
+
+## What's in scope (v1)
+
+| Capability | How you declare it |
+|---|---|
+| HTTP API | An Express or NestJS app, marked with the [`http()`](../reference/decorators-and-markers.md#http) marker. |
+| Scheduled jobs | [`@Cron`](../reference/decorators-and-markers.md#cron) (class) or [`cron()`](../reference/decorators-and-markers.md#cron-marker) (function) |
+| Queue consumers | [`@Queue`](../reference/decorators-and-markers.md#queue) (class) or [`queue()`](../reference/decorators-and-markers.md#queue-marker) (function) |
+| Per-environment deploys | [Stages](../guides/stages-and-environments.md) (`--stage`) |
+| Env vars | [`env`](../guides/environment-variables.md) in config |
+
+Next: **[Installation](./installation.md)**.

package/content/getting-started/quickstart.md

@@ -0,0 +1,164 @@
+---
+title: Quickstart
+description: From an empty folder to a live HTTPS endpoint in a few minutes.
+order: 3
+---
+
+# Quickstart
+
+This walks you from zero to a deployed app with an HTTP endpoint, a scheduled
+job, and a queue consumer.
+
+## 1. Create a project
+
+```bash
+mkdir my-api && cd my-api
+npm init -y
+npm install express
+npm install -D @alzulejos/laranja typescript
+npm install @alzulejos/laranja-decorators
+```
+
+> laranja supports **Express** and **NestJS**. For Nest, see the
+> [HTTP apps guide](../guides/http-apps.md#nestjs).
+
+## 2. Write your app
+
+Mark your app with [`http()`](../reference/decorators-and-markers.md#http) and
+export it. laranja finds it by reading your code — so there's nothing to wire up
+in config:
+
+```ts
+// src/app.ts
+import express from "express";
+import { http } from "@alzulejos/laranja-decorators";
+
+const app = express();
+app.get("/", (_req, res) => res.json({ ok: true, stage: process.env.STAGE }));
+app.get("/users/:id", (req, res) => res.json({ id: req.params.id }));
+
+export default http(app);
+```
+
+Add a scheduled job and a queue consumer (optional). There are two styles — pick
+whichever fits your codebase.
+
+```ts tab="Function"
+// src/jobs.ts
+import { cron, queue, rate } from "@alzulejos/laranja-decorators";
+
+export async function refreshCache() {
+  console.log("refreshing cache…");
+}
+cron(rate(5, "minutes"), refreshCache);
+
+export async function sendEmail(body: unknown) {
+  console.log("sending", body);
+}
+queue({ name: "emails", batchSize: 10 }, sendEmail);
+```
+
+```ts tab="Class"
+// src/jobs.ts
+import { Cron, Queue, rate } from "@alzulejos/laranja-decorators";
+
+export class Jobs {
+  @Cron(rate(5, "minutes"))
+  async refreshCache() {}
+
+  @Queue({ name: "emails", batchSize: 10 })
+  async sendEmail(body: unknown) {}
+}
+```
+
+## 3. Sign in and configure
+
+Run the scaffolder. It prompts for your **laranja API key** (from the dashboard),
+validates it, stores it in `~/.laranja/auth.json`, and lets you pick or create a
+**dashboard project** — filling in `name` and `projectId` for you:
+
+```bash
+npx laranja init
+```
+
+The generated `laranja.config.ts` looks like this (edit `region`, `env`, and
+`compute` to taste):
+
+```ts
+// laranja.config.ts
+import type { LaranjaConfig } from "@alzulejos/laranja-decorators";
+
+const config: LaranjaConfig = {
+  name: "my-api",
+  // From your laranja dashboard — identifies this project on the server.
+  projectId: "proj_…",
+  region: "us-east-1",
+  env: { LOG_LEVEL: "info" },
+  // Default compute for every function (the HTTP proxy + each cron/queue).
+  compute: { memory: 256, timeout: 30 },
+};
+
+export default config;
+```
+
+Because the app is marked with `http()` in code, the config stays minimal — the
+HTTP app is declared there, not in config. See the
+**[config reference](../reference/config-file.md)**.
+
+## 4. Preview the plan
+
+`plan` shows what a deploy would do: it synthesizes your template on the server,
+diffs it against what's deployed in your AWS account, and tags each resource
+**created / changed / unchanged**. It's **read-only** — nothing is applied, and it
+never counts against your deploy limit.
+
+```bash
+npx laranja plan
+```
+
+```
+Plan for "my-api-dev"
+
++ http     HTTP   2 routes → proxy Lambda + Function URL
++ daily    Cron   Lambda + EventBridge rule
++ emails   Queue  SQS + consumer Lambda
+
+8 AWS resources  +8 created  =0 unchanged
+```
+
+On this first run nothing is deployed yet, so everything shows as `+` created.
+
+## 5. Deploy
+
+```bash
+npx laranja deploy
+```
+
+The first deploy to a new account/region prompts you to **bootstrap** (a
+one-time setup in your account). When it finishes you'll see your live URL:
+
+```
+🌐 http   https://abc123.lambda-url.us-east-1.on.aws/
+```
+
+Hit it:
+
+```bash
+curl https://abc123.lambda-url.us-east-1.on.aws/
+# {"ok":true,"stage":"dev"}
+```
+
+## 6. Iterate
+
+```bash
+npx laranja logs            # tail CloudWatch logs (pick a function)
+npx laranja plan            # see what a deploy would change
+npx laranja deploy          # ship again
+npx laranja destroy         # tear it all down
+```
+
+## Next steps
+
+- Ship to multiple environments: **[Stages & environments](../guides/stages-and-environments.md)**.
+- Understand what was created: **[What gets deployed](../reference/what-gets-deployed.md)**.
+- Go deeper on jobs and queues: **[Cron jobs](../guides/cron-jobs.md)**, **[Queues](../guides/queues.md)**.

package/content/guides/cron-jobs.md

@@ -0,0 +1,129 @@
+---
+title: Cron jobs
+description: Run functions on a schedule with @Cron or cron().
+order: 2
+---
+
+# Cron jobs
+
+A cron job is a function that runs on a schedule. Each one becomes
+[its own Lambda plus an EventBridge rule](../reference/what-gets-deployed.md#cron--lambda--eventbridge-rule).
+
+## Class style — `@Cron`
+
+Decorate a method with [`@Cron`](../reference/decorators-and-markers.md#cron) and
+give it a [schedule](./schedules.md):
+
+```ts
+import { Cron, rate, every } from "@alzulejos/laranja-decorators";
+
+export class Jobs {
+  @Cron(rate(5, "minutes"))
+  async refreshCache() {
+    // …
+  }
+
+  @Cron(every("day"))
+  async nightlyCleanup() {
+    // …
+  }
+
+  @Cron({ schedule: "cron(0 12 * * ? *)", id: "daily-report" })
+  async sendReport() {
+    // …
+  }
+}
+```
+
+The handler's logical id defaults to `‹Class›-‹method›`; pass `id` to set a
+stable, explicit name (which also drives the Lambda's name).
+
+## Function style — `cron()`
+
+If you don't use classes, register a standalone exported function with
+[`cron()`](../reference/decorators-and-markers.md#cron-marker):
+
+```ts
+import { cron, rate } from "@alzulejos/laranja-decorators";
+
+export async function refreshCache() {
+  // …
+}
+
+cron(rate(5, "minutes"), refreshCache);
+```
+
+The function's name becomes the resource id unless you pass an explicit `id`:
+
+```ts
+cron({ schedule: every("hour"), id: "hourly-sync" }, refreshCache);
+```
+
+## NestJS
+
+In a Nest app, `@Cron` goes on a normal provider — with injected dependencies —
+and you can keep the schedule syntax you already use (a
+[node-cron string or `CronExpression`](./schedules.md#node-cron-expressions-nestjsschedule-compatibility)).
+Swapping the import from `@nestjs/schedule` is usually the only change:
+
+```ts
+// tasks.service.ts
+import { Injectable } from "@nestjs/common";
+import { Cron, CronExpression } from "@alzulejos/laranja-decorators";  // ← was @nestjs/schedule
+
+@Injectable()
+export class TasksService {
+  constructor(private readonly reports: ReportsService) {}   // real DI
+
+  @Cron(CronExpression.EVERY_30_MINUTES)
+  async sweep() {
+    await this.reports.rebuild();   // `this.reports` is injected
+  }
+}
+```
+
+Because the method runs on a real provider, laranja resolves it through your
+app's dependency-injection container instead of `new`-ing the class. Point it at
+your module **once** with the [`workers()`](../reference/decorators-and-markers.md#workers)
+marker:
+
+```ts
+// src/main.ts (or a dedicated file)
+import { workers } from "@alzulejos/laranja-decorators";
+import { AppModule } from "./app.module";
+
+export default workers(AppModule);   // build a DI context from this module
+```
+
+Pass `AppModule` for the whole graph, or a leaner module you compose if you want
+a smaller cold start. Like the Nest [HTTP path](./http-apps.md#nestjs), laranja
+packages your **compiled** `dist/` output — run `nest build` before deploying so
+the DI metadata exists.
+
+## Schedules
+
+Schedules are written with the portable `rate()` / `every()` builders, or as a
+raw expression string. See the **[Schedules reference](./schedules.md)** for the
+full set of options.
+
+```ts
+@Cron(rate(30, "minutes"))                 // every 30 minutes
+@Cron(every("hour"))                       // every hour (shorthand for rate(1, "hour"))
+@Cron({ schedule: "cron(0 9 * * ? *)" })   // raw AWS cron: 09:00 UTC daily
+```
+
+## Runtime behavior
+
+- Each cron runs in its **own Lambda**, isolated from your HTTP app and other
+  jobs.
+- Memory and timeout come from [`compute`](../reference/config-file.md#compute)
+  (default `{ memory: 256, timeout: 30 }`) and can be overridden per cron id in
+  [`resources`](../reference/config-file.md#resources).
+- All [config `env`](./environment-variables.md) and `STAGE` are
+  available via `process.env`.
+
+## Related
+
+- [Schedules](./schedules.md)
+- [`@Cron` / `cron()` reference](../reference/decorators-and-markers.md#cron)
+- [Queues](./queues.md)

package/content/guides/environment-variables.md

@@ -0,0 +1,108 @@
+---
+title: Environment variables
+description: Declare env vars in config or in code, and supply their values per stage.
+order: 5
+---
+
+# Environment variables
+
+Every Lambda laranja deploys receives a set of environment variables, available
+through `process.env` as usual. There are two ways to declare them.
+
+## Static values in config
+
+Put plain, commit-safe values in the `env` map in your config. They're injected
+into **every** function (HTTP proxy, cron, and queue consumers):
+
+```ts
+// laranja.config.ts
+const config: LaranjaConfig = {
+  name: "my-api",
+  env: {
+    LOG_LEVEL: "info",
+    API_BASE_URL: "https://api.example.com",
+  },
+};
+```
+
+```ts
+// anywhere in your app
+const level = process.env.LOG_LEVEL; // "info"
+```
+
+Use this for non-sensitive configuration that's the same everywhere: log levels,
+public URLs, feature flags.
+
+## Values from your environment — `env()`
+
+When a value should come from your shell or CI instead of your repo, wrap the
+variable name with the `env()` helper where you read it:
+
+```ts
+import { env } from "@alzulejos/laranja-decorators";
+
+const dbUrl = env("DATABASE_URL"); // same as process.env.DATABASE_URL at runtime
+```
+
+laranja finds every `env("…")` in your code and makes sure that variable is set
+on **every** deployed function — no more filling them in by hand in the AWS
+console. At deploy time it reads each value from your own environment and sends
+it straight to the function; the value is never written into your repo.
+
+The name must be a **string literal** — `env("DATABASE_URL")`, not
+`env(someVariable)` — so laranja can discover it just by reading your code.
+
+### Supplying the values
+
+Set the variables in the shell or CI job you deploy from:
+
+```bash
+DATABASE_URL=postgres://… laranja deploy --stage prod
+```
+
+- **Missing a value?** By default laranja deploys anyway and warns you which ones
+  were empty — a typo never blocks a deploy. Pass `--strict` to fail the deploy
+  instead.
+- **Re-deploying without re-supplying a value?** The previously deployed value is
+  kept, so you don't have to pass every variable on every deploy.
+
+## The `STAGE` variable
+
+laranja always injects `STAGE`, set to the active [stage](./stages-and-environments.md)
+(`"dev"` by default, or whatever `--stage` resolved to). You don't declare it:
+
+```ts
+app.get("/", (_req, res) => res.json({ stage: process.env.STAGE }));
+```
+
+If you also define `STAGE` in `env`, your value wins.
+
+## Per-stage values
+
+Because [`--stage`](./stages-and-environments.md) selects the
+environment at deploy time, the common pattern is one pipeline per stage, each
+supplying its own values:
+
+- **Shared, non-sensitive defaults** → the `env` map in config.
+- **Per-environment values** → declare them with `env()` and provide them from
+  each pipeline's environment.
+
+```bash
+# dev pipeline
+LOG_LEVEL=debug laranja deploy --stage dev
+# prod pipeline
+LOG_LEVEL=warn  laranja deploy --stage prod
+```
+
+## Secrets
+
+`env()` keeps values out of your repo, but they still land in the Lambda's plain
+environment — readable by anyone with access to the function's configuration. For
+true secrets (API keys, DB passwords), that's not enough. First-class secrets
+support is on the roadmap; until then, read them at runtime from a secret store
+(e.g. AWS SSM Parameter Store / Secrets Manager) inside your handler.
+
+## Related
+
+- [Config file](../reference/config-file.md)
+- [Stages & environments](./stages-and-environments.md)