@juuno-sdk/cli 4.0.2 → 4.2.0

package/dist/cli/src/deploy-backend/index.js

@@ -0,0 +1,196 @@
+import { existsSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { getApiUrl, getAuthToken } from '../auth/index.js';
+import { spawnSync } from '../utils/bin.js';
+import { fetchContext, withTimeout } from './context.js';
+import { getErrorMessage } from '../utils/error.js';
+import { describeOutcome, report, } from './outcome.js';
+import { buildMetadata, isModuleFile, moduleContentType, parseWranglerConfig, resolveApiUrl, resolveEnvConfig, scriptName, } from './wrangler-config.js';
+/**
+ * Far longer than the context read: this uploads the whole bundle and the server
+ * then provisions stores and runs the tenant's migrations before answering.
+ */
+const DEPLOY_TIMEOUT_MS = 180_000;
+/**
+ * Main script entry point.
+ */
+export async function deployBackend(options) {
+    try {
+        await run(options);
+    }
+    catch (error) {
+        // Matches the other commands: one line the developer can act on, not a
+        // stack trace. The messages here already name the fix.
+        console.error(`❌ ${getErrorMessage(error)}`);
+        process.exit(1);
+    }
+}
+/**
+ * Resolve the plan, print the metadata, and deploy.
+ */
+async function run(options) {
+    const plan = await resolvePlan(options);
+    if (options.printMetadata) {
+        const { script, env, namespace, metadata } = plan;
+        console.log(JSON.stringify({ script, env, namespace, metadata }, null, 2));
+        return;
+    }
+    const target = plan.namespace ? `${plan.env} (${plan.namespace})` : plan.env;
+    console.log(`Deploying '${plan.script}' to ${target} via ${plan.api}`);
+    const outcome = await postDeploy(plan, bundle(plan.workerDir, plan.env));
+    report(outcome);
+}
+/**
+ * Bundle the worker with its own pinned wrangler.
+ *
+ * Shelled out rather than imported so the version in the worker's
+ * devDependencies is the one that runs — a bundler mismatch between the CLI and
+ * the worker would be a genuinely confusing failure — and so the CLI takes no
+ * wrangler dependency of its own.
+ */
+function bundle(workerDir, env) {
+    const outDir = join(workerDir, 'dist');
+    // Emptied first: wrangler writes into --outdir without clearing it, and
+    // everything left there is uploaded as a module. A renamed entry point or a
+    // dropped code-split chunk would otherwise ship alongside the current build
+    // forever — dead weight against the Worker size limit, and a bundle whose
+    // contents depend on what happened to be built in this directory before.
+    rmSync(outDir, { recursive: true, force: true });
+    const bundled = spawnSync('npx', ['wrangler', 'deploy', '--env', env, '--dry-run', '--outdir', outDir], { cwd: workerDir, stdio: 'inherit' });
+    // spawnSync reports rather than throws, so both failures are checked here:
+    // the spawn itself (wrangler missing, PATH wrong) and a non-zero exit.
+    if (bundled.error) {
+        throw new Error(`Could not run wrangler: ${bundled.error.message}`);
+    }
+    if (bundled.status !== 0) {
+        throw new Error(`wrangler exited with code ${bundled.status ?? 'unknown'}.`);
+    }
+    if (!existsSync(outDir)) {
+        throw new Error(`wrangler produced no output at ${outDir}.`);
+    }
+    const modules = collectModules(outDir);
+    if (!modules.length) {
+        throw new Error(`No module files in ${outDir}.`);
+    }
+    return modules;
+}
+/**
+ * Every module in the dry-run output, as parts to upload.
+ *
+ * The walk is recursive because wrangler writes a code-split chunk or an
+ * imported `.wasm` into a subdirectory, and a flat read would leave it out of
+ * the upload entirely — either rejected for a missing module, or accepted and
+ * then throwing `No such module` on the first request.
+ */
+export function collectModules(outDir) {
+    // Separators normalised on the way in: Cloudflare addresses a module by a
+    // posix path, and a nested entry on Windows arrives here as `lib\chunk.js`.
+    const names = readdirSync(outDir, {
+        encoding: 'utf8',
+        recursive: true,
+    }).map((entry) => entry.replaceAll('\\', '/'));
+    return names.filter(isModuleFile).map((name) => ({
+        name,
+        contents: new Uint8Array(readFileSync(join(outDir, name))),
+    }));
+}
+/**
+ * Work out what would be deployed, without deploying it.
+ *
+ * Everything here is a read, so `--print-metadata` can stop straight afterwards
+ * and show exactly what a real run would send.
+ */
+async function resolvePlan(options) {
+    const workerDir = resolve(options.dir ?? process.cwd());
+    const configPath = join(workerDir, 'wrangler.jsonc');
+    if (!existsSync(configPath)) {
+        throw new Error(`No wrangler.jsonc in ${workerDir}. Run this from a worker directory, or pass --dir.`);
+    }
+    // Resolved before the token, not after. On the --email/--password path
+    // getAuthToken() posts the credentials to this url, so a guard that ran
+    // afterwards would refuse a cleartext connection the password had already gone
+    // over. Passed back in so the checked value is the one that gets used.
+    const api = resolveApiUrl(getApiUrl(options));
+    const token = await getAuthToken({ ...options, apiUrl: api });
+    // The profile picks the API; the API states its environment. That single
+    // answer then selects the wrangler env to bundle, so the bindings that get
+    // built and the namespace that receives them can never disagree.
+    const { env, namespace } = await fetchContext(api, token);
+    const config = parseWranglerConfig(readFileSync(configPath, 'utf8'));
+    // Throws naming the envs the file does declare, which is the useful error
+    // when a worker has not been set up for the environment you are pointed at.
+    const resolved = resolveEnvConfig(config, env);
+    return {
+        workerDir,
+        api,
+        token,
+        env,
+        namespace,
+        // The raw config, not the resolved one: naming the script is the one place
+        // wrangler suffixes rather than inherits. See scriptName().
+        script: scriptName(config, env),
+        metadata: buildMetadata(resolved),
+    };
+}
+/**
+ * The multipart upload Cloudflare's Workers API expects, as the platform
+ * forwards it: the script name, the metadata, and one part per module.
+ */
+function buildUploadForm(plan, modules) {
+    const form = new FormData();
+    form.append('script', plan.script);
+    form.append('metadata', JSON.stringify(plan.metadata));
+    for (const module of modules) {
+        form.append(module.name, new Blob([module.contents], { type: moduleContentType(module.name) }), basename(module.name));
+    }
+    return form;
+}
+/**
+ * Read the body, tolerating one that will not parse.
+ *
+ * The status is still meaningful, and every status has an answer without a body.
+ * An abort is not a parse failure, though — that is the deploy running past its
+ * timeout, which has its own answer — so it propagates rather than being flatted
+ * into an empty body and reported as "HTTP 200: no error message".
+ */
+export async function readDeployResponse(response) {
+    try {
+        return (await response.json());
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'TimeoutError') {
+            throw error;
+        }
+        return {};
+    }
+}
+/**
+ * Upload the modules and say what happened.
+ *
+ * Returns the outcome rather than a status and a body, because nothing upstream
+ * wants the transport details — the only question is what happened, and
+ * describeOutcome() is what answers it.
+ */
+async function postDeploy(plan, modules) {
+    // One timeout around the request and the body read together. The deploy is
+    // not finished until the server has answered in full, so an abort partway
+    // through the body is the same "may still have landed" situation as an abort
+    // before the headers, and gets the same sentence.
+    const { status, body } = await withTimeout(async () => {
+        const response = await fetch(`${plan.api}/api/v1/developer/app-backends/deploy`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${plan.token}`,
+                Accept: 'application/json',
+            },
+            body: buildUploadForm(plan, modules),
+            signal: AbortSignal.timeout(DEPLOY_TIMEOUT_MS),
+        });
+        return {
+            status: response.status,
+            body: await readDeployResponse(response),
+        };
+    }, `The deploy did not finish within ${DEPLOY_TIMEOUT_MS / 1000}s. It may still ` +
+        "have landed — check the app's Backend tab in Superadmin before retrying.");
+    return describeOutcome(status, body, modules.map((module) => module.name), plan.api);
+}

package/dist/cli/src/deploy-backend/outcome.js

@@ -0,0 +1,85 @@
+/**
+ * Reading a deploy response, and saying what happened.
+ *
+ * Two functions, split so the decision is separable from the printing:
+ * `describeOutcome` is pure and decides, `report` performs. Kept apart from the
+ * command because the distinction they draw is a safety property rather than
+ * presentation — a 404 means the platform refused before anything reached
+ * Cloudflare, so nothing is live and the CLI can fail loudly; any other failure
+ * may have uploaded the script and then failed a later step, so the server's own
+ * message is the only accurate account of what happened and is passed through
+ * untouched.
+ *
+ * Getting that backwards would either hide a live half-deploy behind a tidy
+ * error, or tell a developer to go and register something that already exists.
+ */
+/**
+ * What the response means, given the modules that were sent.
+ *
+ * A body of `{ success: false }` on a 200 counts as a failure — the endpoint
+ * reports step failures in the body, so the HTTP status alone is not the answer.
+ */
+export function describeOutcome(status, body, moduleNames, api) {
+    const failed = status < 200 || status >= 300 || body.success !== true;
+    if (!failed) {
+        const lines = [
+            `\n${body.message ?? 'Deployed.'}`,
+            `  modules: ${moduleNames.join(', ')}`,
+        ];
+        // Only apps with a database report one, so its absence is not a gap.
+        if (body.schema_version != null) {
+            lines.push(`  schema version: ${body.schema_version}`);
+        }
+        return { kind: 'success', lines };
+    }
+    // A 404 alone does not mean "not registered". The deploy endpoint answers one
+    // with its own error envelope; a wrong --api, a proxy, or an instance too old
+    // to have the route answers one with HTML or nothing, which postDeploy turns
+    // into an empty body. Telling that developer to go and register a backend they
+    // already registered sends them looking in the wrong place entirely, so the
+    // envelope is what distinguishes them.
+    if (status === 404) {
+        if (typeof body.error === 'string') {
+            return {
+                kind: 'unregistered',
+                message: `${body.error}\n` +
+                    'Register it in Superadmin, on the Backend tab of the app it serves.',
+            };
+        }
+        return {
+            kind: 'failed',
+            message: `\nDeploy failed (HTTP 404): ${api}/api/v1/developer/app-backends/deploy ` +
+                'did not answer as the deploy endpoint.\nCheck the profile’s API url — ' +
+                'a 404 without an error body usually means the request never reached it.',
+        };
+    }
+    return {
+        kind: 'failed',
+        message: `\nDeploy failed (HTTP ${status}): ${body.error ?? 'no error message'}`,
+        details: body.errors ? JSON.stringify(body.errors, null, 2) : undefined,
+    };
+}
+/**
+ * Turn an outcome into output and an exit code.
+ *
+ * Only `unregistered` throws, and only because nothing was uploaded: the caller
+ * wraps a throw as a one-line `❌ …`, which is the right shape for "this was
+ * refused, here is the fix". A failure that may have half-landed must not be
+ * wrapped, so it is written straight to stderr and the exit code is set by hand.
+ */
+export function report(outcome) {
+    if (outcome.kind === 'unregistered') {
+        throw new Error(outcome.message);
+    }
+    if (outcome.kind === 'failed') {
+        console.error(outcome.message);
+        if (outcome.details) {
+            console.error(outcome.details);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    for (const line of outcome.lines) {
+        console.log(line);
+    }
+}

package/dist/cli/src/deploy-backend/wrangler-config.js

@@ -0,0 +1,277 @@
+/**
+ * Pure helpers for a Workers-for-Platforms deploy: building the payload from a
+ * worker's wrangler.jsonc, and resolving where to send it.
+ *
+ * Kept free of I/O so the part that fails silently — the metadata — is directly
+ * testable. See wrangler-config.test.ts.
+ */
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+/**
+ * Normalise the API base, and refuse to put the developer token on a cleartext
+ * connection.
+ *
+ * Loopback stays exempt so a local Laravel over http still works. Anything else
+ * must be https, because the next thing the caller does with this value is send
+ * a bearer token to it.
+ */
+export function resolveApiUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`API url must be absolute, got: ${value}`);
+    }
+    if (url.protocol !== 'https:' && !LOOPBACK_HOSTS.has(url.hostname)) {
+        throw new Error(`API url must use https (or a loopback host for local development), got: ${value}`);
+    }
+    return value.replace(/\/$/, '');
+}
+/**
+ * Binding types wrangler does NOT inherit from the top level into `env.<name>`.
+ * Everything else (main, compatibility_date, compatibility_flags, …) is
+ * inherited. Getting this wrong in the lenient direction is the dangerous one:
+ * it would ship a top-level store binding into an environment that deliberately
+ * declared none.
+ */
+const NOT_INHERITED = [
+    'vars',
+    'kv_namespaces',
+    'd1_databases',
+    'r2_buckets',
+    'queues',
+    'routes',
+    'route',
+    'durable_objects',
+];
+/**
+ * Binding kinds buildMetadata cannot express.
+ *
+ * Cloudflare treats the metadata part as the authoritative binding list, so one
+ * dropped here deploys a worker whose binding is simply absent: the deploy
+ * reports success and the first request that touches it 500s, with nothing in
+ * the output connecting the two. Refused instead, until the platform endpoint
+ * provisions them the way it already does KV and D1.
+ */
+const UNSUPPORTED_BINDINGS = [
+    'r2_buckets',
+    'queues',
+    'durable_objects',
+    'services',
+];
+/**
+ * An env block by name, own properties only.
+ *
+ * `constructor` and `toString` are inherited from Object.prototype, so a plain
+ * lookup finds a function there and sails through a truthiness check — resolving
+ * `--env constructor` to a nonsense config instead of erroring.
+ */
+function ownEnv(config, env) {
+    return Object.prototype.hasOwnProperty.call(config.env ?? {}, env)
+        ? config.env?.[env]
+        : undefined;
+}
+/**
+ * Strip comments and trailing commas from JSONC so JSON.parse accepts it.
+ *
+ * String-aware: a `//` or block-comment opener inside a quoted value is left
+ * alone, as is an escaped quote. Written by hand rather than pulling in a parser
+ * because this is the only JSONC we read and the input is our own.
+ *
+ * The complexity is suppressed rather than refactored. This is a character
+ * scanner: four mutually-exclusive states over one cursor, sharing `out`, `i`
+ * and three flags. Extracting the branches means threading all of that through
+ * helpers or hoisting it into an object, which trades a shape every reader
+ * recognises for one nobody does — and a state machine you have to reassemble
+ * across functions is exactly where an off-by-one hides. The 31 cases in
+ * `__tests__/wrangler-config.test.ts` are what keeps it honest instead.
+ */
+// fallow-ignore-next-line complexity
+export function stripJsonc(source) {
+    let out = '';
+    let inString = false;
+    let inLine = false;
+    let inBlock = false;
+    for (let i = 0; i < source.length; i++) {
+        const c = source[i];
+        const next = source[i + 1];
+        if (inLine) {
+            if (c === '\n') {
+                inLine = false;
+                out += c;
+            }
+            continue;
+        }
+        if (inBlock) {
+            if (c === '*' && next === '/') {
+                inBlock = false;
+                i++;
+            }
+            continue;
+        }
+        if (inString) {
+            out += c;
+            if (c === '\\') {
+                // Copy the escaped character verbatim so \" doesn't end the string.
+                out += next ?? '';
+                i++;
+            }
+            else if (c === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (c === '"') {
+            inString = true;
+            out += c;
+            continue;
+        }
+        if (c === '/' && next === '/') {
+            inLine = true;
+            i++;
+            continue;
+        }
+        if (c === '/' && next === '*') {
+            inBlock = true;
+            i++;
+            continue;
+        }
+        // Trailing comma before a closing brace/bracket. Done here rather than with
+        // a regex over the finished string so a quoted value containing ",}" or
+        // ",]" is left alone — at this point we know we are outside a string.
+        if (c === '}' || c === ']') {
+            out = out.replace(/,\s*$/, '');
+        }
+        out += c;
+    }
+    return out;
+}
+export function parseWranglerConfig(source) {
+    return JSON.parse(stripJsonc(source));
+}
+/**
+ * Flatten a wrangler config for one environment.
+ *
+ * Inherited keys come from the top level unless the environment overrides them;
+ * the binding keys in NOT_INHERITED come from the environment alone, matching
+ * wrangler's own rule.
+ */
+export function resolveEnvConfig(config, env) {
+    const envConfig = ownEnv(config, env);
+    if (!envConfig) {
+        throw new Error(`wrangler.jsonc declares no env "${env}" (found: ${Object.keys(config.env ?? {}).join(', ') || 'none'}).`);
+    }
+    const resolved = { ...config, ...envConfig };
+    delete resolved.env;
+    for (const key of NOT_INHERITED) {
+        if (envConfig[key] === undefined) {
+            delete resolved[key];
+        }
+    }
+    return resolved;
+}
+/**
+ * The entry module's name as it appears in the dry-run output. wrangler compiles
+ * `./src/index.ts` to `dist/index.js`, so the extension is normalised.
+ */
+export function entryModuleName(main) {
+    // Both separators: a wrangler.jsonc authored on Windows can say
+    // "src\\index.ts", and the parts bundle() uploads are named by readdirSync —
+    // bare basenames. Leaving a backslash in would make main_module name a part
+    // that was never sent, and Cloudflare rejects the upload for a missing entry.
+    return main.replace(/^.*[/\\]/, '').replace(/\.(ts|tsx|mts|cts)$/, '.js');
+}
+/**
+ * Build the `metadata` part for the platform deploy endpoint.
+ *
+ * Store bindings are emitted **by name only**. The platform provisions the
+ * store and fills the id — sending one would make it adopt an existing store
+ * instead, and nothing would report that it had. Note the two are not
+ * symmetric: KV's id field is `namespace_id`, D1's is `id`, and neither is set
+ * here.
+ */
+export function buildMetadata(resolved) {
+    if (!resolved.main) {
+        throw new Error('wrangler.jsonc has no "main" entry point.');
+    }
+    if (!resolved.compatibility_date) {
+        throw new Error('wrangler.jsonc has no "compatibility_date".');
+    }
+    const unsupported = UNSUPPORTED_BINDINGS.filter((key) => resolved[key] !== undefined);
+    if (unsupported.length) {
+        throw new Error(`wrangler.jsonc declares bindings this deploy path cannot send: ${unsupported.join(', ')}.`);
+    }
+    const bindings = [];
+    for (const kv of resolved.kv_namespaces ?? []) {
+        bindings.push({ type: 'kv_namespace', name: kv.binding });
+    }
+    for (const d1 of resolved.d1_databases ?? []) {
+        bindings.push({ type: 'd1', name: d1.binding });
+    }
+    for (const [name, value] of Object.entries(resolved.vars ?? {})) {
+        // Every var ships as plain text, so an object or array would arrive as
+        // "[object Object]" or a comma-joined list — a binding that looks present in
+        // the metadata and is not the value the worker reads. `typeof null` is
+        // 'object' too, and "null" is no better. Refused rather than corrupted.
+        if (typeof value === 'object') {
+            throw new Error(`var "${name}" must be a string, number or boolean — this deploy path sends vars as plain text.`);
+        }
+        bindings.push({ type: 'plain_text', name, text: String(value) });
+    }
+    const metadata = {
+        main_module: entryModuleName(resolved.main),
+        compatibility_date: resolved.compatibility_date,
+    };
+    if (resolved.compatibility_flags?.length) {
+        metadata.compatibility_flags = resolved.compatibility_flags;
+    }
+    if (bindings.length) {
+        metadata.bindings = bindings;
+    }
+    // Forwarded as written; the platform validates it and turns observability on
+    // when the key is absent, so this only matters for sampling settings or an
+    // explicit opt-out.
+    if (resolved.observability !== undefined) {
+        metadata.observability = resolved.observability;
+    }
+    return metadata;
+}
+/**
+ * The tenant script name wrangler will have built for this environment.
+ *
+ * Read off the raw config rather than the resolved one because the rule is not
+ * inheritance: an env that declares its own `name` uses it verbatim, and one
+ * that does not gets `<top-level-name>-<env>`. The merged config cannot tell the
+ * two apart, so reading it would address the upload to `google-reviews` for a
+ * bundle wrangler built as `google-reviews-prod` — refused as unregistered, or
+ * worse, landing on whichever tenant already holds that name.
+ */
+export function scriptName(config, env) {
+    const envName = ownEnv(config, env)?.name;
+    if (envName) {
+        return envName;
+    }
+    if (!config.name) {
+        throw new Error('wrangler.jsonc has no "name".');
+    }
+    return `${config.name}-${env}`;
+}
+/** Files in the dry-run output that belong in the upload. */
+export function isModuleFile(filename) {
+    // Anchored, which is what excludes sourcemaps: `index.js.map` ends in `.map`,
+    // so it never matches in the first place.
+    return /\.(js|mjs|wasm)$/.test(filename);
+}
+/**
+ * The Content-Type of a module part, which is how Cloudflare decides what kind
+ * of module it is — not a formality. `application/javascript+module` makes it an
+ * ES module and `application/wasm` a CompiledWasm one, so labelling a `.wasm`
+ * as JavaScript would have Cloudflare try to parse the binary as source and
+ * reject the upload. isModuleFile() already accepts `.wasm`, so the two have to
+ * agree about what that means.
+ */
+export function moduleContentType(filename) {
+    return filename.endsWith('.wasm')
+        ? 'application/wasm'
+        : 'application/javascript+module';
+}

package/dist/cli/src/utils/api.js

@@ -1,4 +1,15 @@
 import { getErrorMessage } from './error.js';
+/**
+ * A non-2xx answer from the developer API. It keeps the status, so a caller
+ * can treat one status, such as a 404, as an answer and not as a failure.
+ */
+export class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
 /**
  * Fetch JSON from a developer-API endpoint with bearer-token auth, throwing
  * a useful error on non-2xx responses (status, statusText, body). Used by
@@ -14,7 +25,7 @@ export async function fetchAuthorisedJson(url, token) {
     });
     if (!response.ok) {
         const body = await response.text();
-        throw new Error(`${response.status} ${response.statusText}\n${body}`);
+        throw new HttpError(response.status, `${response.status} ${response.statusText}\n${body}`);
     }
     return (await response.json());
 }

package/dist/cli/src/utils/bin.js

@@ -0,0 +1,23 @@
+import crossSpawn from 'cross-spawn';
+/**
+ * Spawning a package-manager binary, portably.
+ *
+ * `npx`, `pnpm` and `yarn` are shell scripts on POSIX and `.cmd` shims on
+ * Windows, and neither Node nor libuv will run a `.cmd` from `spawn` without a
+ * shell — `CreateProcess` cannot execute one, and since the fix for
+ * CVE-2024-27980 Node refuses rather than silently routing through cmd.exe.
+ * Naming the shim (`npx.cmd`) fixes PATH resolution and not the spawn.
+ *
+ * Doing it correctly means invoking `cmd.exe /d /s /c` with the command and
+ * every argument escaped for cmd's parser, plus a second round of escaping for
+ * shims under `node_modules/.bin`, and `windowsVerbatimArguments` so Node does
+ * not re-quote what was just escaped. `shell: true` is the wrong shortcut: it
+ * hands the whole line to cmd.exe to re-parse, so a worker directory containing
+ * `&` or `^` becomes a command.
+ *
+ * cross-spawn already does all of it, is the ecosystem's answer to this exact
+ * problem, and was already in the tree transitively. Preferred over a local
+ * reimplementation, which is where the escaping bugs live.
+ */
+export const spawn = crossSpawn;
+export const spawnSync = crossSpawn.sync;