@alzulejos/laranja-core 0.2.4

package/dist/client.js

@@ -0,0 +1,240 @@
+/**
+ * The laranja API client — the CLI's side of the wire contract in `api.ts`.
+ *
+ * Zero-dep: uses the global `fetch` (Node 18+). Only the Infra IR ever crosses
+ * the wire (see `SynthRequest`); the user's source code never leaves the machine.
+ */
+import { ENDPOINTS, } from "./api.js";
+import { loadStoredApiKey } from "./auth.js";
+import { CONFIG_FILENAME } from "./config.js";
+/** Default server URL for local development. Override with `LARANJA_API_URL`. */
+export const DEFAULT_API_URL = "https://api.laranja.io";
+/** Where to reach the server. Env override lets us point at prod later. */
+export function resolveApiUrl() {
+    return (process.env.LARANJA_API_URL ?? DEFAULT_API_URL).replace(/\/+$/, "");
+}
+/**
+ * The caller's API key. Precedence: `LARANJA_API_KEY` env var (CI / one-off
+ * override) wins, then the key persisted by `laranja init` (~/.laranja/auth.json).
+ * The env override means a stored login never blocks a different key in CI.
+ */
+export function resolveApiKey() {
+    return ((process.env.LARANJA_API_KEY?.trim() || undefined) ?? loadStoredApiKey());
+}
+/** A failed API call — carries the server's error code so callers can branch. */
+export class ApiRequestError extends Error {
+    code;
+    status;
+    upgradeUrl;
+    constructor(code, message, status, upgradeUrl) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.upgradeUrl = upgradeUrl;
+        this.name = "ApiRequestError";
+    }
+}
+/** Base URL of the laranja dashboard web app. Override with `LARANJA_DASHBOARD_URL` for local dev. */
+export const DASHBOARD_URL = (process.env.LARANJA_DASHBOARD_URL ?? "https://laranja.io/app").replace(/\/+$/, "");
+/** Dashboard page where users create / manage their API keys. */
+export const DASHBOARD_KEYS_URL = `${DASHBOARD_URL}/user`;
+/**
+ * True when an error means the API key itself is the problem — missing,
+ * expired, or deleted — as opposed to an entitlement issue.
+ *
+ * The server is inconsistent about how it reports a bad key (it leans on
+ * NestJS's generic exceptions rather than our structured `ApiErrorCode`):
+ *   - a proper `401`,
+ *   - a `400 { error: "Bad Request", message: "Invalid API KEY" }`,
+ *   - a `403 { error: "Forbidden", message: "Forbidden resource" }` when an
+ *     expired/deleted key trips the auth guard.
+ * So we treat any 401/403, or a message of "Invalid API KEY", as a bad key.
+ *
+ * The one 403 that is NOT a key problem is a *real* entitlement failure ("valid
+ * key, not entitled"), which uses our structured contract: lower-case `code:
+ * "forbidden"` + an `upgradeUrl`. NestJS's generic guard rejection instead puts
+ * capital-`F` `"Forbidden"` in the body's `error` field, so the two don't
+ * collide — we exclude only the lower-case structured code.
+ */
+export function isAuthKeyError(err) {
+    if (!(err instanceof ApiRequestError))
+        return false;
+    if (err.code === "forbidden")
+        return false; // structured entitlement, not a bad key
+    if (err.code === "project_access")
+        return false; // valid key, project-access issue
+    return (err.status === 401 ||
+        err.status === 403 ||
+        /invalid\s+api\s+key/i.test(err.message));
+}
+/**
+ * Turn an `ApiRequestError` into a friendly, actionable one-or-many-line
+ * message, prefixed with the failing step (e.g. "Handshake failed"). Bad-key
+ * errors get create-a-new-key guidance; an unreachable server gets a "is it
+ * running?" hint; everything else falls back to the server's own message.
+ */
+export function apiErrorMessage(prefix, err) {
+    if (isAuthKeyError(err)) {
+        return [
+            `${prefix} — your API key is invalid, expired, or was deleted.`,
+            "",
+            `  Create a new key at ${DASHBOARD_KEYS_URL}, then export it:`,
+            "      export LARANJA_API_KEY=<NEW_KEY>",
+            "",
+            "  (laranja also reads a saved key from ~/.laranja/auth.json —",
+            "   a stale one there can cause this too.)",
+        ].join("\n");
+    }
+    if (err.code === "project_access") {
+        return [
+            `${prefix} — you don't have access to this project.`,
+            "",
+            "  Your API key is fine, but the project it's pointing at isn't reachable.",
+            "  This usually means one of:",
+            "    • the project was deleted from your dashboard,",
+            "    • you were removed from it, or",
+            `    • the "projectId" in ${CONFIG_FILENAME} is wrong.`,
+            "",
+            `  Check your projects at ${DASHBOARD_URL} and update "projectId" in ${CONFIG_FILENAME}.`,
+        ].join("\n");
+    }
+    const hint = err.status === 0
+        ? `is the server running at ${resolveApiUrl()}?`
+        : err.message;
+    return `${prefix} — ${hint}`;
+}
+async function apiRequest(method, endpoint, opts) {
+    const url = `${opts.baseUrl ?? resolveApiUrl()}${endpoint}`;
+    let res;
+    try {
+        res = await fetch(url, {
+            method,
+            headers: {
+                "x-api-key": opts.apiKey,
+                ...(opts.projectId ? { "x-project-id": opts.projectId } : {}),
+                ...(opts.body !== undefined
+                    ? { "Content-Type": "application/json" }
+                    : {}),
+            },
+            body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+        });
+    }
+    catch (cause) {
+        throw new ApiRequestError("server_error", `Could not reach the laranja server at ${url}`, 0);
+    }
+    if (!res.ok) {
+        const err = (await res.json().catch(() => undefined));
+        throw new ApiRequestError(err?.error ?? "server_error", err?.message ?? `Request failed (${res.status})`, res.status, err?.upgradeUrl);
+    }
+    // Read defensively: some endpoints return a bare (unquoted) id string — e.g.
+    // destroy — or an empty body, neither of which `res.json()` can parse.
+    const text = await res.text();
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/**
+ * `GET /v1/me` — validate the API key and fetch the caller's tier/limits.
+ * Used by `laranja init` to handshake with the server.
+ */
+export function getMe(apiKey, baseUrl) {
+    return apiRequest("GET", ENDPOINTS.me, { apiKey, baseUrl });
+}
+/**
+ * `POST /v1/project` — create a project (name only) from the CLI and get back
+ * its server id. User-scoped: authed by the API key, no `x-project-id`.
+ */
+export function createProject(name, apiKey, baseUrl) {
+    const body = { name };
+    return apiRequest("POST", ENDPOINTS.project, {
+        apiKey,
+        baseUrl,
+        body,
+    });
+}
+/**
+ * `POST /v1/synth` — send the Infra IR, get back a CloudFormation template
+ * (or, for paid tiers, a CDK project). Only the IR crosses the wire; the
+ * dashboard `projectId` rides in the `x-project-id` header.
+ */
+export function postSynth(req, apiKey, projectId, baseUrl) {
+    return apiRequest("POST", ENDPOINTS.synth, {
+        apiKey,
+        projectId,
+        baseUrl,
+        body: req,
+    });
+}
+/**
+ * `POST /v1/diff` — a read-only synth: same input as `/synth`, returns a template
+ * to diff against the deployed stack, but creates NO deployment row.
+ */
+export function postDiff(req, apiKey, projectId, baseUrl) {
+    return apiRequest("POST", ENDPOINTS.diff, {
+        apiKey,
+        projectId,
+        baseUrl,
+        body: req,
+    });
+}
+/**
+ * `POST /v1/eject` — generate a standalone, owned CDK project from the IR. The
+ * server gates this on the caller's entitlement (403 if not allowed). Nothing is
+ * persisted; the client writes the returned files to disk.
+ */
+export function postEject(req, apiKey, projectId, baseUrl) {
+    return apiRequest("POST", ENDPOINTS.eject, {
+        apiKey,
+        projectId,
+        baseUrl,
+        body: req,
+    });
+}
+/**
+ * `POST /v1/report` — send a free-form CLI failure report, scoped to the user
+ * (api key) + project (project id). Diagnostics only; the body shape is open.
+ */
+export function postReport(report, apiKey, projectId, baseUrl) {
+    return apiRequest("POST", ENDPOINTS.report, {
+        apiKey,
+        projectId,
+        baseUrl,
+        body: report,
+    });
+}
+/**
+ * `PATCH /v1/deployment/:id` — advance a deployment's status. Sent with
+ * `{ status: "STARTED", region }` before touching AWS, then `{ status: "SUCCESS"
+ * | "FAILED" }` once the deploy settles. The dashboard `projectId` rides in the
+ * `x-project-id` header, consistent with the rest of the deploy/destroy calls.
+ */
+export function patchDeployment(deploymentId, body, apiKey, projectId, baseUrl) {
+    return apiRequest("PATCH", ENDPOINTS.deployment(deploymentId), {
+        apiKey,
+        projectId,
+        baseUrl,
+        body,
+    });
+}
+/**
+ * `POST /v1/deployment/:id/resources` — report the deployed inventory after a
+ * successful deploy. Body is WRAPPED (`{ resources }`); a bare array 500s the BE.
+ */
+export function postDeploymentResources(deploymentId, body, apiKey, projectId, baseUrl) {
+    return apiRequest("POST", ENDPOINTS.deploymentResources(deploymentId), { apiKey, projectId, baseUrl, body });
+}
+/**
+ * `POST /v1/deployment/destory` — open a teardown deployment row and get its id,
+ * so a destroy can drive the same status lifecycle (STARTED → SUCCESS/FAILED).
+ * Tolerates either a `{ deploymentId }` body or a bare id string.
+ */
+export async function postDestroy(req, apiKey, projectId, baseUrl) {
+    const res = await apiRequest("POST", ENDPOINTS.deploymentDestroy, { apiKey, projectId, baseUrl, body: req });
+    return typeof res === "string" ? res : res.deploymentId;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,151 @@
+import type { CloudProvider, ComputeConfig, Framework } from "./ir.js";
+/** Queue-only tuning knobs (SQS + event-source). */
+export interface QueueTuning {
+    /** FIFO content-based dedup (FIFO queues only). */
+    contentBasedDedup?: boolean;
+    /** Seconds a message stays hidden while processed. Must be >= the consumer timeout. */
+    visibilityTimeout?: number;
+    /** Seconds to wait gathering a fuller batch before invoking. */
+    maxBatchingWindow?: number;
+    /** Report per-message failures so only failed items retry. */
+    reportBatchItemFailures?: boolean;
+    /** Seconds an undelivered message is retained on the source queue. */
+    messageRetention?: number;
+}
+/** Cron-only tuning knobs (schedule + async-invoke). */
+export interface CronTuning {
+    /** IANA timezone for the schedule. */
+    timezone?: string;
+    /** Async-invoke retry attempts (0–2). */
+    retryAttempts?: number;
+    /** Max age (seconds) of an event before async retries are abandoned. */
+    maxEventAge?: number;
+}
+/**
+ * DLQ for a queue — the id of another declared queue, plus the required
+ * `maxReceiveCount` (after N failed receives → dead-letter). `Q` is the union of
+ * this project's queue names, so the generated config autocompletes `queue` to a
+ * real target; it defaults to `string` for the untyped fallback.
+ */
+export interface QueueDlq<Q extends string = string> {
+    queue: Q;
+    maxReceiveCount: number;
+}
+/** DLQ for a cron — the id of another declared queue. A failed async invoke dead-letters immediately, so there's no receive count. */
+export interface CronDlq<Q extends string = string> {
+    queue: Q;
+}
+/** Per-resource overrides for the HTTP proxy: compute knobs only. */
+export type HttpResourceConfig = ComputeConfig;
+/**
+ * Compute for one worker Lambda, keyed by its module name. Under consolidation a
+ * Nest module is a single function, so memory/timeout/etc. live here — not on the
+ * individual cron/queue, which only owns its trigger (see `*TriggerConfig`).
+ */
+export type WorkerResourceConfig = ComputeConfig;
+/**
+ * A queue's TRIGGER‑level tuning (SQS + event source + DLQ) — no compute. Used for
+ * a grouped Nest queue, whose compute lives on its worker module. `Q` (the queue‑
+ * name union) types the DLQ target for autocomplete.
+ */
+export interface QueueTriggerConfig<Q extends string = string> extends QueueTuning {
+    dlq?: QueueDlq<Q>;
+}
+/** A cron's TRIGGER‑level tuning (schedule + async‑invoke + DLQ) — no compute. */
+export interface CronTriggerConfig<Q extends string = string> extends CronTuning {
+    dlq?: CronDlq<Q>;
+}
+/**
+ * Per-resource overrides for a STANDALONE queue consumer (Express, or a function‑
+ * style queue in Nest): compute + trigger, since the handler is its own Lambda.
+ */
+export interface QueueResourceConfig<Q extends string = string> extends ComputeConfig, QueueTriggerConfig<Q> {
+}
+/** Per-resource overrides for a STANDALONE cron: compute + trigger (its own Lambda). */
+export interface CronResourceConfig<Q extends string = string> extends ComputeConfig, CronTriggerConfig<Q> {
+}
+/**
+ * The loose, kind-agnostic override shape — every knob optional and `dlq`'s
+ * `maxReceiveCount` optional. Used by the scanner (which validates per kind at
+ * scan time) and by the untyped `resources: Record<string, ResourceConfig>`
+ * fallback. Opt into `TypedLaranjaConfig` (from the generated `laranja.types.ts`)
+ * for per-kind compile-time typing that requires `maxReceiveCount` on a queue DLQ
+ * and rejects a foreign knob before deploy instead of only at scan time.
+ */
+export interface ResourceConfig extends ComputeConfig, QueueTuning, CronTuning {
+    dlq?: {
+        queue: string;
+        maxReceiveCount?: number;
+    };
+}
+/** User-authored config, loaded from `laranja.config.ts`. */
+export interface LaranjaConfig {
+    /** App name — used for the CloudFormation stack and resource naming. */
+    name: string;
+    /**
+     * Project id from your laranja dashboard. Identifies this project on the
+     * server (scoping, limits, deploy timeline); sent as the `x-project-id`
+     * header on `/synth`. Obtain it when you create the project in the dashboard.
+     */
+    projectId?: string;
+    /** Target cloud. Only "aws" is implemented today. Defaults to "aws". */
+    provider?: CloudProvider;
+    region?: string;
+    /** AWS named profile to deploy with. */
+    profile?: string;
+    /** Override framework detection. */
+    framework?: Framework;
+    /** Deployment stage; part of resource names (e.g. "dev", "prod"). Defaults to "dev". */
+    stage?: string;
+    /** Plain env injected into every Lambda. */
+    env?: Record<string, string>;
+    /**
+     * Emit a per-app-stage monitoring dashboard (`<name>-<stage>`) with per-function
+     * invocations / errors / throttles / duration for the HTTP proxy and every
+     * cron/queue consumer. Provider-neutral — each back half maps it to its own
+     * primitives. HTTP status classes (2xx/4xx/5xx) come later with API Gateway.
+     * Defaults to true.
+     */
+    monitoring?: boolean;
+    /**
+     * Default compute config (memory, timeout, …) applied to every function — the
+     * HTTP proxy and each cron/queue consumer. Override per-resource via `resources`.
+     */
+    compute?: ComputeConfig;
+    /**
+     * Per-resource overrides keyed by resource id ("http", or a cron/queue id).
+     * Each merges on top of `compute`, field by field. An unknown id is a hard
+     * error at scan time so a typo never silently no-ops.
+     */
+    resources?: Record<string, ResourceConfig>;
+}
+export declare const CONFIG_FILENAME = "laranja.config.ts";
+/** Overrides applied on top of the loaded config — e.g. a `--stage` CLI flag. */
+export interface ConfigOverrides {
+    /** Wins over `config.stage`. Used by the `--stage`/`-s` flag for per-stage pipelines. */
+    stage?: string;
+}
+/**
+ * The CloudFormation stack name for a project + stage: `<name>-<stage>`.
+ *
+ * Stage is part of the stack name (not just the Lambda names) so two stages can
+ * be deployed to the SAME account without colliding — one definition, two
+ * independent stacks. With separate dev/prod accounts the suffix is harmless.
+ * Single source of truth: every command must derive the stack name from here.
+ */
+export declare function stackName(name: string, stage: string): string;
+/**
+ * The monitoring dashboard's physical name: `<name>-<stage>`, sanitized to the
+ * chars CloudWatch allows (A–Z a–z 0–9 - _) and capped at 255.
+ *
+ * Single source of truth: the back half names the dashboard from here, and the
+ * client builds the console deep link (`externalUrl`) from here, so the two can
+ * never drift. Provider-neutral name; each back half maps it to its own dashboard.
+ */
+export declare function dashboardName(name: string, stage: string): string;
+/**
+ * Loads `laranja.config.ts` from the project dir. Runs under tsx, so importing a
+ * TypeScript config module Just Works. Returns the config with defaults applied,
+ * then any `overrides` (e.g. a `--stage` flag) layered on top.
+ */
+export declare function loadConfig(projectDir: string, overrides?: ConfigOverrides): Promise<Required<Pick<LaranjaConfig, "env" | "stage" | "provider" | "monitoring">> & LaranjaConfig>;

package/dist/config.js

@@ -0,0 +1,89 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { existsSync } from "node:fs";
+export const CONFIG_FILENAME = "laranja.config.ts";
+/**
+ * The CloudFormation stack name for a project + stage: `<name>-<stage>`.
+ *
+ * Stage is part of the stack name (not just the Lambda names) so two stages can
+ * be deployed to the SAME account without colliding — one definition, two
+ * independent stacks. With separate dev/prod accounts the suffix is harmless.
+ * Single source of truth: every command must derive the stack name from here.
+ */
+export function stackName(name, stage) {
+    return `${name}-${stage}`;
+}
+/**
+ * The monitoring dashboard's physical name: `<name>-<stage>`, sanitized to the
+ * chars CloudWatch allows (A–Z a–z 0–9 - _) and capped at 255.
+ *
+ * Single source of truth: the back half names the dashboard from here, and the
+ * client builds the console deep link (`externalUrl`) from here, so the two can
+ * never drift. Provider-neutral name; each back half maps it to its own dashboard.
+ */
+export function dashboardName(name, stage) {
+    return `${name}-${stage}`.replace(/[^A-Za-z0-9_-]/g, "-").slice(0, 255);
+}
+/**
+ * `laranja.config.ts` is ESM (`export default`), but the project it lives in is
+ * almost always "typeless" — a Nest/Express app whose package.json has no
+ * `"type": "module"` because its own build is CommonJS. Importing the config then
+ * makes Node detect the format by syntax and print a MODULE_TYPELESS_PACKAGE_JSON
+ * warning the user can't act on without breaking their app's CJS build. It's
+ * laranja's config, so laranja swallows exactly that one warning code — everything
+ * else Node emits still gets through. Idempotent; installed once, lazily.
+ */
+let typelessWarningSilenced = false;
+function silenceTypelessConfigWarning() {
+    if (typelessWarningSilenced)
+        return;
+    typelessWarningSilenced = true;
+    const original = process.emitWarning.bind(process);
+    process.emitWarning = ((warning, ...args) => {
+        const opt = args[0];
+        const code = opt && typeof opt === "object" ? opt.code : args[1];
+        if (code === "MODULE_TYPELESS_PACKAGE_JSON")
+            return;
+        return original(warning, ...args);
+    });
+}
+/**
+ * Loads `laranja.config.ts` from the project dir. Runs under tsx, so importing a
+ * TypeScript config module Just Works. Returns the config with defaults applied,
+ * then any `overrides` (e.g. a `--stage` flag) layered on top.
+ */
+export async function loadConfig(projectDir, overrides = {}) {
+    const file = path.join(projectDir, CONFIG_FILENAME);
+    if (!existsSync(file)) {
+        throw new Error(`No ${CONFIG_FILENAME} found in ${projectDir}. Run \`laranja init\` first.`);
+    }
+    silenceTypelessConfigWarning();
+    const mod = await import(pathToFileURL(file).href);
+    const cfg = mod.default ?? mod.config;
+    if (!cfg) {
+        throw new Error(`${CONFIG_FILENAME} must \`export default\` a config object.`);
+    }
+    if (!cfg.name) {
+        throw new Error(`${CONFIG_FILENAME}: "name" is required — run \`laranja init\` to link this directory to a project.`);
+    }
+    // The HTTP app is declared in code via an `http(app)` marker, which the scanner
+    // resolves — there's no config field for it. The scanner raises a clear error
+    // if there's ultimately nothing to deploy.
+    // Only AWS is implemented today. Reject any other provider up front so a
+    // forward-compatible config field never silently deploys to the wrong (or no)
+    // back-half. This guard goes away per-arm once a discriminated union of real
+    // providers exists.
+    if (cfg.provider && cfg.provider !== "aws") {
+        throw new Error(`${CONFIG_FILENAME}: provider "${cfg.provider}" isn't supported yet — only "aws" today.`);
+    }
+    return {
+        stage: "dev",
+        provider: "aws",
+        monitoring: true,
+        env: {},
+        ...cfg,
+        // Overrides win over both defaults and the config file (only when set).
+        ...(overrides.stage ? { stage: overrides.stage } : {}),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/env.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Client-side resolution of the env var NAMES discovered in user code (the IR's
+ * `envKeys`) against a source of values — by default the process environment.
+ *
+ * This runs on the developer's / CI machine at deploy time. The resolved VALUES
+ * are injected into the Lambda's environment locally and never travel to the
+ * server: only the names are in the IR (see `InfraIR.envKeys`).
+ */
+/** The outcome of resolving declared env names against a value source. */
+export interface ResolvedEnv {
+    /** name -> value, for every declared key that had a value. */
+    resolved: Record<string, string>;
+    /** Declared keys that had no value in the source (unset). */
+    missing: string[];
+}
+/**
+ * Resolve `envKeys` against `source` (defaults to `process.env`). A key is
+ * "missing" only when it is unset (`undefined`); an explicit empty string is a
+ * deliberate value and is kept.
+ */
+export declare function resolveDeclaredEnv(envKeys: string[], source?: NodeJS.ProcessEnv): ResolvedEnv;
+/**
+ * A valid environment-variable NAME: a letter or underscore, then letters, digits,
+ * or underscores. This is the conventional POSIX/shell shape and a superset of what
+ * AWS Lambda accepts, so anything failing this can never be a real env var — it's a
+ * typo (e.g. `env("MY_SECRET)")`, where the `)` slipped inside the quotes).
+ */
+export declare const ENV_NAME_PATTERN: RegExp;
+/** Whether `key` is a syntactically valid environment-variable name. */
+export declare function isValidEnvName(key: string): boolean;
+/**
+ * The CloudFormation Parameter logical id for an env key. Each code-discovered
+ * `env("NAME")` becomes a stack Parameter (so the value is supplied at deploy
+ * time, never baked into the template). Logical ids must be alphanumeric, so
+ * non-alphanumerics are stripped — this is the single source of truth shared by
+ * the stack (which declares the Parameter) and the deploy step (which supplies
+ * its value).
+ *
+ * NOTE: the stripping is lossy — `MY_SECRET` and `MYSECRET` both map to
+ * `EnvMYSECRET`, and two such keys collide as a duplicate-construct error at synth.
+ * Validated names (see `isValidEnvName`) make that rare, but a fully collision-free
+ * scheme (hash suffix) is a breaking change: the CLI and the server's bundled synth
+ * both compute this id, so it must only change in a coordinated release of both.
+ */
+export declare function envParamName(key: string): string;
+/**
+ * The Lambda environment variable name that carries a declared queue's SQS URL.
+ * The synth injects `LARANJA_QUEUE_URL_<name>` into EVERY function's env (so any
+ * function can produce to any queue), and the runtime producer — `getQueue(name)`
+ * — reads the same key. This is the single source of truth shared by laranja-cdk
+ * (which sets the value) and laranja-runtime (which reads it); keyed by the
+ * queue's declared `name` (the user-facing identity), with non-alphanumerics
+ * collapsed to "_" so it is a valid env-var name.
+ */
+export declare function queueUrlEnvName(name: string): string;

package/dist/env.js

@@ -0,0 +1,66 @@
+/**
+ * Client-side resolution of the env var NAMES discovered in user code (the IR's
+ * `envKeys`) against a source of values — by default the process environment.
+ *
+ * This runs on the developer's / CI machine at deploy time. The resolved VALUES
+ * are injected into the Lambda's environment locally and never travel to the
+ * server: only the names are in the IR (see `InfraIR.envKeys`).
+ */
+/**
+ * Resolve `envKeys` against `source` (defaults to `process.env`). A key is
+ * "missing" only when it is unset (`undefined`); an explicit empty string is a
+ * deliberate value and is kept.
+ */
+export function resolveDeclaredEnv(envKeys, source = process.env) {
+    const resolved = {};
+    const missing = [];
+    for (const key of envKeys) {
+        const value = source[key];
+        if (value === undefined)
+            missing.push(key);
+        else
+            resolved[key] = value;
+    }
+    return { resolved, missing };
+}
+/**
+ * A valid environment-variable NAME: a letter or underscore, then letters, digits,
+ * or underscores. This is the conventional POSIX/shell shape and a superset of what
+ * AWS Lambda accepts, so anything failing this can never be a real env var — it's a
+ * typo (e.g. `env("MY_SECRET)")`, where the `)` slipped inside the quotes).
+ */
+export const ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Whether `key` is a syntactically valid environment-variable name. */
+export function isValidEnvName(key) {
+    return ENV_NAME_PATTERN.test(key);
+}
+/**
+ * The CloudFormation Parameter logical id for an env key. Each code-discovered
+ * `env("NAME")` becomes a stack Parameter (so the value is supplied at deploy
+ * time, never baked into the template). Logical ids must be alphanumeric, so
+ * non-alphanumerics are stripped — this is the single source of truth shared by
+ * the stack (which declares the Parameter) and the deploy step (which supplies
+ * its value).
+ *
+ * NOTE: the stripping is lossy — `MY_SECRET` and `MYSECRET` both map to
+ * `EnvMYSECRET`, and two such keys collide as a duplicate-construct error at synth.
+ * Validated names (see `isValidEnvName`) make that rare, but a fully collision-free
+ * scheme (hash suffix) is a breaking change: the CLI and the server's bundled synth
+ * both compute this id, so it must only change in a coordinated release of both.
+ */
+export function envParamName(key) {
+    return `Env${key.replace(/[^A-Za-z0-9]/g, "")}`;
+}
+/**
+ * The Lambda environment variable name that carries a declared queue's SQS URL.
+ * The synth injects `LARANJA_QUEUE_URL_<name>` into EVERY function's env (so any
+ * function can produce to any queue), and the runtime producer — `getQueue(name)`
+ * — reads the same key. This is the single source of truth shared by laranja-cdk
+ * (which sets the value) and laranja-runtime (which reads it); keyed by the
+ * queue's declared `name` (the user-facing identity), with non-alphanumerics
+ * collapsed to "_" so it is a valid env-var name.
+ */
+export function queueUrlEnvName(name) {
+    return `LARANJA_QUEUE_URL_${name.replace(/[^A-Za-z0-9]/g, "_")}`;
+}
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAiB,EACjB,SAA4B,OAAO,CAAC,GAAG;IAEvC,MAAM,QAAQ,GAA2B,EAAE,CAAC;IAC5C,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;;YACtC,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAC7B,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AAC/B,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,0BAA0B,CAAC;AAE3D,wEAAwE;AACxE,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,MAAM,GAAG,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC,EAAE,CAAC;AAClD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,qBAAqB,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,GAAG,CAAC,EAAE,CAAC;AACnE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./ir.js";
+export * from "./config.js";
+export * from "./env.js";
+export * from "./schedule.js";
+export * from "./nest-schedule.js";
+export * from "./api.js";
+export * from "./client.js";
+export * from "./auth.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from "./ir.js";
+export * from "./config.js";
+export * from "./env.js";
+export * from "./schedule.js";
+export * from "./nest-schedule.js";
+export * from "./api.js";
+export * from "./client.js";
+export * from "./auth.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC"}