@ryanatkn/gro 0.112.0

package/dist/docs/task.md

@@ -0,0 +1,377 @@
+# task
+
+> task runner for
+> [Gro](https://github.com/ryanatkn/gro)
+
+## contents
+
+- [what](#what)
+- [usage](#usage)
+- [why?](#why)
+
+## what
+
+A Gro `Task` is just an object with a `run` function and some optional metadata.
+Gro prefers conventions and code over configuration,
+and its task runner leverages the filesystem as the API
+and defers composition to the user in regular TypeScript modules.
+
+> Tasks are a special Gro construct.
+> If you want to simply execute regular TypeScript files,
+> use the `gro run` task, which works like the normal `node` CLI
+> but uses the Gro loader to support `.ts`.
+
+- Gro automatically discovers [all `*.task.ts` files](../docs/tasks.md)
+  in your source directory, so creating a new task
+  is as simple as [creating a new file](#define-a-task), no config needed,
+  but part of the convention is that Gro expects all source code to be in `src/`
+- task definitions are just objects with an async `run` function and some optional properties,
+  so composing tasks is explicit in your code, just like any other module
+  (but there's also the helper `invoke_task`: see more below)
+- on the command line, tasks replace the concept of commands,
+  so running them is as simple as `gro <task>`,
+  and in code the task object's `run` function has access to CLI args;
+  to view [the available tasks](https://github.com/ryanatkn/gro/blob/main/src/lib/docs/tasks.md)
+  run `gro` with no arguments
+- tasks optionally use [zod](https://github.com/colinhacks/zod) schemas
+  for `args` types, runtime parsing with helpful validation errors,
+  and automatic help output, with DRY co-located definitions
+- it's easy to hook into or override any of Gro's builtin tasks,
+  like [`gro test`](/src/lib/test.task.ts) and [`gro gen`](/src/lib/gen.task.ts)
+  (tasks are copy-paste friendly! just update the imports)
+- the task execution environment is filesystem agnostic by default; `run` receives a
+  [`Task_Context` argument](#user-content-types-task-and-taskcontext) with an `fs` property
+- the `Task_Context` provides a rich baseline context object
+  for both development/build tasks and one-off script authoring/execution;
+  it attempts to be portable and extensibile, but there's a _lot_ of room for improvement
+- it's fast because it imports only the modules that your chosen tasks need
+
+The task runner's purpose is to provide an ergonomic interface
+between the CLI, build tools, and app code.
+As a developer, it's nice to be able to reuse TypeScript modules in every context.
+
+## usage
+
+### show all available tasks
+
+```bash
+# This looks through `src/` in both the current working directory
+# and Gro's source for all files matching `*.task.ts` and logs them out.
+$ gro
+```
+
+> notice that Gro is hardcoded to expect all tasks to be in `src/` --
+> it would be nice to loosen this up, but the API isn't obvious to me right now
+
+### show tasks in a directory
+
+```bash
+# Logs all `*.task.ts` files in `src/lib/some/dir` and `gro/src/lib/some/dir`.
+# If no tasks are found, it displays an error.
+$ gro some/dir
+```
+
+> To learn more about the Gro CLI path conventions,
+> see [the `input_paths` comments](../input_path.ts)
+
+### run a task
+
+```bash
+# This runs `src/lib/some/file.task.ts`,
+# or if it doesn't exist, `gro/src/lib/some/file.task.ts`.
+# If neither exists, it displays an error.
+$ gro some/file arg1 arg2 --arg3 example
+
+# This runs `gro/src/lib/some/file.task.ts` directly
+# without checking the current working directory,
+# and displays an error if it doesn't exist.
+$ gro gro/some/file
+```
+
+### define a task
+
+```ts
+// src/lib/some/file.task.ts
+import type {Task} from '@ryanatkn/gro';
+
+export const task: Task = {
+	run: async ({log, args}) => {
+		log.info('CLI args', args); // => {_: ['arg1', 'arg2'], arg3: 'example'}
+		await whatever();
+	},
+};
+```
+
+The minimum:
+
+```ts
+// src/lib/some/minimal.task.ts
+export const task = {
+	run: () => console.log('a minimal example'),
+};
+```
+
+Minimum with [`Args`](#task-args):
+
+```ts
+// src/lib/some/withargs.task.ts
+import type {Task} from '@ryanatkn/gro';
+import {z} from 'zod';
+
+export const Args = z
+	.object({
+		arg: z.number({description: 'example number arg'}).default(2),
+	})
+	.strict();
+export type Args = z.infer<typeof Args>;
+
+export const task: Task = {
+	Args,
+	run: async ({args}) => {
+		args.arg; // `number` that defaults to `2`
+	},
+};
+```
+
+### type `Task`
+
+```ts
+import type {Task} from '@ryanatkn/gro';
+
+export interface Task<
+	T_Args = Args, // same as `z.infer<typeof Args>`
+	T_Args_Schema extends z.ZodType = z.ZodType,
+	T_Return = unknown,
+> {
+	run: (ctx: Task_Context<T_Args>) => Promise<T_Return>;
+	summary?: string;
+	Args?: T_Args_Schema;
+}
+```
+
+### type `Task_Context`
+
+```ts
+import type {Task_Context} from '@ryanatkn/gro';
+
+export interface Task_Context<T_Args = object> {
+	args: T_Args;
+	config: Gro_Config;
+	log: Logger;
+	timings: Timings;
+	invoke_task: (task_name: string, args?: Args, config?: Gro_Config) => Promise<void>;
+}
+```
+
+### run a task inside another task with `invoke_task`
+
+Because Gro tasks are just functions,
+you can directly import them from within other tasks and run them.
+However, we recommend using the `invoke_task` helper
+for its ergonomics and automatic logging and diagnostics.
+
+The `invoke_task` helper uses Gro's task resolution rules
+to allow user code to override builtin tasks.
+For example, Gro's `check.task.ts` calls `invoke_task('test')`
+so that it calls your `src/lib/test.task.ts` if it exists
+and falls back to `gro/src/lib/test.task.ts` if not.
+
+It's less important to use `invoke_task` over explicit imports in user code
+because you don't need to rely on the task override rules to get desired behavior,
+but the logging and diagnostics it provides are nice to have.
+
+```bash
+gro some/file
+```
+
+```ts
+// src/lib/some/file.task.ts
+import type {Task} from '@ryanatkn/gro';
+
+export const task: Task = {
+	run: async ({args, invoke_task}) => {
+		// runs `src/lib/some/file.task.ts`, automatically forwarding `args`
+		await invoke_task('some/file');
+		// as documented above, the following is similar but lacks nice features:
+		// await (await import('./some/file.task.js')).run(ctx);
+
+		// runs `src/lib/other/file.task.ts` and falls back to `gro/src/other/file.task.ts`,
+		// forwarding both custom args and a different event emitter (warning: spaghetti)
+		await invoke_task(
+			'other/file',
+			{...args, optionally: 'extended'},
+			optionalEventEmitterForSubtree,
+			optionalDevFlagForSubtree,
+			optionalFsForSubtree,
+		);
+
+		// runs `gro/src/lib/other/file.task.ts` directly, bypassing any local version
+		await invoke_task('gro/other/file');
+	},
+};
+```
+
+### hook into one of [Gro's builtin tasks](../docs/tasks.md)
+
+```bash
+# This normally loads Gro's version of the test task at `gro/src/lib/test.task.ts`,
+# but projects can define `src/lib/test.task.ts` to extend or replace it.
+$ gro test
+```
+
+```ts
+// src/lib/test.task.ts
+import type {Task} from '@ryanatkn/gro';
+
+export const task: Task = {
+	run: async ({args, invoke_task}) => {
+		await doSomethingFirst();
+		// As discussed in the `invoke_task` section above,
+		// it's possible to `import {task as groBuiltinTestTask} from '@ryanatkn/gro/test.task.js'`
+		// and then call `groBuiltinTestTask.run` directly,
+		// but that loses some important benefits.
+		// Still, the task is available to import if you want it for any reason!
+		await invoke_task('gro/test', {...args, optionally: 'extended'}, newEventEmitterForSubtree);
+		await emailEveryoneWithTestResults();
+	},
+};
+```
+
+Note that when hooking into [Gro's builtin tasks](../docs/tasks.md),
+like `test.task.ts` above, you don't have to call its version.
+You can copy/paste an existing task and customize it,
+rewrite a task from scratch, compose them together, or whatever is needed for each project.
+
+### task `Args`
+
+The **`Args` property** of each `Task` (not the task context **`args` param** described above!)
+is an optional [zod](https://github.com/colinhacks/zod) schema.
+Using zod has some benefits:
+
+- automatically print helpful text on the CLI with `gro` and `gro taskname --help`
+- automated args parsing/validation using the schema with initialized defaults
+- type safety using args in tasks
+- concise source of truth
+
+```ts
+// src/lib/dosomething.task.ts
+import type {Task} from '@ryanatkn/gro';
+import type {z} from 'zod';
+
+export const Args = z
+	.object({
+		_: z.array(z.string(), {description: 'rest args'}).default([]),
+		yepyep: z.string({description: 'helpful info'}).default('ya'),
+		okcool: z.number({description: 'that prints to the CLI'}).default(1234),
+		maybee: z.boolean({description: 'and optional args work too'}),
+	})
+	.strict();
+export type Args = z.infer<typeof Args>;
+
+export const task: Task<Args> = {
+	Args,
+	run: async ({args}) => {
+		args._; // string[]
+		args.yepyep; // string
+		args.okcool; // number
+		args.maybee; // boolean | undefined
+	},
+};
+```
+
+Running `gro dosomething --help` prints the schema information in a friendly format.
+
+### task args forwarding
+
+Some builtin Gro tasks call external commands like
+[`svelte-kit`](https://github.com/sveltejs/kit),
+[`vite`](https://github.com/vitejs/vite),
+[`uvu`](https://github.com/lukeed/uvu),
+[`tsc`](https://github.com/microsoft/typescript),
+and [`prettier`](https://github.com/prettier/prettier).
+Gro supports generic agnostic args forwarding to these tasks via the `--` pattern:
+for example, to forward args to `svelte-kit` and `uvu`, no matter which task invokes them,
+use `gro taskname --taskname-arg -- uvu --arg1 neat --arg2 22 -- svelte-kit --arg3`.
+
+Any number of sections separated by `--` may be defined, and the first arg
+that appears after each `--` is assumed to be the CLI command.
+If `gro taskname` or its invoked tasks don't call `uvu` or `svelte-kit`,
+the `--` args will be ignored.
+
+There's one special case for task args forwarding: running Gro tasks.
+If `gro` is the command following a `--`, e.g. the second `gro` of
+`gro taskname -- gro taskname2 --a --b`,
+then `--a` and `--b` will be forwarded to `taskname2`.
+Forwarded args to Gro tasks override direct args, including args to `invoke_task`,
+so `gro taskname --a 1 -- gro taskname --a 2` will invoke `taskname` with `{a: 2}`.
+
+### throwing errors
+
+If a task encounters an error, normally it should throw rather than exiting the process.
+This defers control to the caller, like your own parent tasks.
+
+Often, errors that tasks encounter do not need a stack trace,
+and we don't want the added noise to be logged.
+To suppress logging the stack trace for an error,
+throw a `Task_Error`.
+
+```ts
+import {Task, Task_Error} from '@ryanatkn/gro';
+
+export const task: Task = {
+	run: async () => {
+		if (someErrorCondition) {
+			throw new Task_Error('We hit a known error - ignore the stack trace!');
+		}
+	},
+};
+```
+
+## why?
+
+Gro usage on the command line (`gro <taskOrDirectory> [...flags]`)
+looks a lot like using `node`.
+What makes Gro different?
+
+- The `*.task.ts` file name convention signals to Gro that your application
+  contains task modules that conform to some interface.
+  This allows them to be discoverable by convention,
+  so running `gro` displays them all without any config, and it puts generic handles on them,
+  enabling various verbs (e.g. `run`) and structured metadata (e.g. `summary`).
+- Tasks aren't just a script, they can be inspected, composed, and manipulated in code.
+  Task modules do not have any side effects when imported,
+  while Node scripts just execute when imported -
+  their primary purpose is to cause side effects.
+  This is useful in many cases - for example `gro taskname --help`
+  inspects the args schema and other metadata to print help to the console,
+  and `gro` prints the `summary` property of each task it finds.
+  There's lots more to explore here, like task composition
+  and improved DX with new capabilities.
+- Tasks support CLI args that are validated and typesafe
+  via colocated Zod schemas with minimal boilerplate.
+- Module resolution differs and leverages discoverability:
+  - When a task name is given to Gro,
+    it first searches `src/lib/` in the current working directory and
+    falls back to searching the Gro directory.
+    This allows your code and CLI commands to use Gro's builtin tasks
+    or override or extend them without changing how you invoke them.
+    Gro reserves no special behavior for its own commands -
+    `gro test`, `gro gen`, and all the rest are just tasks that all follow the same rules.
+    (see its task at [`src/lib/test.task.ts`](/src/lib/test.task.ts)).
+  - When a directory is given to Gro,
+    it prints all of the tasks found inside it,
+    both relative to the current working directory and Gro's directory.
+    So when you run `gro` by itself,
+    it prints all tasks available both in your project and Gro.
+  - The trailing `.task.ts` in the file path provided to `gro` is optional,
+    so for example, `gro foo/bar` is the same as `gro foo/bar.task.ts`, a nice convenience.
+
+## :turtle:<sub>:turtle:</sub><sub><sub>:turtle:</sub></sub>
+
+Gro's task runner has many inspirations:
+
+- [mgutz/task](https://github.com/mgutz/task)
+- [Gulp](https://github.com/gulpjs/gulp)
+- [@mgutz](https://github.com/mgutz)' [Projmate](https://github.com/projmate/projmate-core)
+- [Grunt](https://github.com/gruntjs/grunt)
+- [npm scripts](https://docs.npmjs.com/v8/using-npm/scripts)

package/dist/docs/tasks.gen.md.d.ts

@@ -0,0 +1,2 @@
+import { type Gen } from '../gen.js';
+export declare const gen: Gen;

package/dist/docs/tasks.gen.md.js

@@ -0,0 +1,60 @@
+import { dirname, relative, basename } from 'node:path';
+import { parse_path_parts, parse_path_segments } from '@ryanatkn/belt/path.js';
+import { strip_start } from '@ryanatkn/belt/string.js';
+import { to_output_file_name } from '../gen.js';
+import { paths, base_path_to_source_id } from '../paths.js';
+import { load_task_modules } from '../task_module.js';
+import { log_error_reasons } from '../print_task.js';
+// This is the first simple implementation of Gro's automated docs.
+// It combines Gro's gen and task systems
+// to generate a markdown file describing all of the project's tasks.
+// Other projects that use Gro should be able to import this module
+// or other otherwise get frictionless access to this specific use case,
+// and they should be able to extend or customize it to any degree.
+// TODO display more info about each task, including a summary and params
+// TODO needs some cleanup and better APIs - paths are confusing and verbose!
+// TODO add backlinks to every document that links to this one
+export const gen = async ({ origin_id, log }) => {
+    const result = await load_task_modules();
+    if (!result.ok) {
+        log_error_reasons(log, result.reasons);
+        throw new Error(result.type);
+    }
+    const tasks = result.modules;
+    // TODO need to get this from project config or something
+    const root_path = parse_path_segments(paths.root).at(-1);
+    const origin_dir = dirname(origin_id);
+    const origin_base = basename(origin_id);
+    const base_dir = paths.source;
+    const relative_path = strip_start(origin_id, base_dir);
+    const relative_dir = dirname(relative_path);
+    // TODO should this be passed in the context, like `defaultOutputFileName`?
+    const output_file_name = to_output_file_name(origin_base);
+    // TODO this is GitHub-specific
+    const root_link = `[${root_path}](/../..)`;
+    // TODO do we want to use absolute paths instead of relative paths,
+    // because GitHub works with them and it simplifies the code?
+    const path_parts = parse_path_parts(relative_dir).map((relative_path_part) => `[${parse_path_segments(relative_path_part).at(-1)}](${relative(origin_dir, base_path_to_source_id(relative_path_part)) || './'})`);
+    const breadcrumbs = '> <sub>' + [root_link, ...path_parts, output_file_name].join(' / ') + '</sub>';
+    // TODO render the footer with the origin_id
+    return `# tasks
+
+${breadcrumbs}
+
+What is a \`Task\`? See [\`task.md\`](./task.md).
+
+## all tasks
+
+${tasks.reduce((taskList, task) => taskList +
+        `- [${task.name}](${relative(origin_dir, task.id)})${task.mod.task.summary ? ` - ${task.mod.task.summary}` : ''}\n`, '')}
+## usage
+
+\`\`\`bash
+$ gro some/name
+\`\`\`
+
+${breadcrumbs}
+
+> <sub>generated by [${origin_base}](${origin_base})</sub>
+`;
+};

package/dist/docs/tasks.md

@@ -0,0 +1,35 @@
+# tasks
+
+> <sub>[gro](/../..) / [lib](..) / [docs](./) / tasks.md</sub>
+
+What is a `Task`? See [`task.md`](./task.md).
+
+## all tasks
+
+- [build](../build.task.ts) - build the project
+- [changeset](../changeset.task.ts) - call changeset with gro patterns
+- [check](../check.task.ts) - check that everything is ready to commit
+- [clean](../clean.task.ts) - remove temporary dev and build files, and optionally prune git branches
+- [commit](../commit.task.ts) - commit and push to a new branch
+- [deploy](../deploy.task.ts) - deploy to a branch
+- [dev](../dev.task.ts) - start SvelteKit and other dev plugins
+- [format](../format.task.ts) - format source files
+- [gen](../gen.task.ts) - run code generation scripts
+- [lint](../lint.task.ts) - run eslint
+- [publish](../publish.task.ts) - bump version, publish to npm, and git push
+- [release](../release.task.ts) - publish and deploy
+- [run](../run.task.ts) - execute a file with the loader, like `node` but works for TypeScript
+- [sync](../sync.task.ts) - run `gro gen`, update `package.json`, and optionally `npm i` to sync up
+- [test](../test.task.ts) - run tests with uvu
+- [typecheck](../typecheck.task.ts) - run tsc on the project without emitting any files
+- [upgrade](../upgrade.task.ts) - upgrade deps
+
+## usage
+
+```bash
+$ gro some/name
+```
+
+> <sub>[gro](/../..) / [lib](..) / [docs](./) / tasks.md</sub>
+
+> <sub>generated by [tasks.gen.md.ts](tasks.gen.md.ts)</sub>

package/dist/docs/test.md

@@ -0,0 +1,52 @@
+# test
+
+Gro integrates [`uvu`](https://github.com/lukeed/uvu) for tests:
+
+```bash
+gro test # run all tests with Gro's default `*.test.ts` pattern
+gro test thing.test somedir test/a.+b # run tests matching regexp patterns
+```
+
+> Running `gro test [...args]` calls `uvu`'s `parse` and `run` helpers
+> inside Gro's normal [task context](/src/lib/docs/task.md) instead of using the `uvu` CLI.
+> Gro typically defers to a tool's CLI, so it can transparently forward args without wrapping,
+> but in this case `uvu` doesn't support [loaders](https://nodejs.org/api/esm.html#loaders)
+> for running TypeScript files directly.
+> `uvu` does support require hooks, but Gro prefers the loader API.
+
+Like other tasks, use `--help` to see the args info:
+
+```bash
+gro test --help
+```
+
+outputs:
+
+```
+gro test: run tests
+[...args]  string[]           ["\\.test\\.ts$"]  file patterns to test
+bail       boolean            false              the bail option to uvu run, exit immediately on failure
+cwd        string             undefined          the cwd option to uvu parse
+ignore     string | string[]  undefined          the ignore option to uvu parse
+```
+
+[`gro test`](/src/lib/test.task.ts) runs all `*.test.ts`
+files in your project by default using the regexp `"\\.test\\.ts$"`.
+So to add a new test, create a new file:
+
+```ts
+// by convention, create `src/lib/thing.ts`
+// to test `src/lib/thing.test.ts`
+import {test} from 'uvu';
+import * as assert from 'uvu/assert';
+
+import {thing} from '$lib/thing.js';
+
+test('the thing', async () => {
+	assert.equal(thing, {expected: true});
+});
+
+test.run();
+```
+
+See [the `uvu` docs](https://github.com/lukeed/uvu) for more.

package/dist/env.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="node" />
+export declare const load_env: (dev: boolean, visibility: 'public' | 'private', public_prefix: string, private_prefix: string, env_dir?: string, env_files?: string[], ambient_env?: NodeJS.ProcessEnv) => Promise<Record<string, string>>;
+export declare const merge_envs: (envs: Array<Record<string, string | undefined>>, visibility: 'public' | 'private', public_prefix: string, private_prefix: string) => Record<string, string>;
+export declare const is_private_env: (key: string, public_prefix: string, private_prefix: string) => boolean;
+export declare const is_public_env: (key: string, public_prefix: string, private_prefix: string) => boolean;
+/**
+ * Loads a single env value without merging it into `process.env`.
+ * By default searches process.env, then a local `.env` if one exists, then `../.env` if it exists.
+ */
+export declare const load_from_env: (key: string, paths?: string[]) => Promise<string | undefined>;

package/dist/env.js

@@ -0,0 +1,47 @@
+import dotenv from 'dotenv';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { exists } from './fs.js';
+export const load_env = async (dev, visibility, public_prefix, private_prefix, env_dir, env_files = ['.env', '.env.' + (dev ? 'development' : 'production')], ambient_env = process.env) => {
+    const envs = await Promise.all(env_files
+        .map(async (path) => (await load(env_dir === undefined ? path : resolve(env_dir, path))))
+        .filter(Boolean));
+    envs.push(ambient_env);
+    return merge_envs(envs, visibility, public_prefix, private_prefix);
+};
+const load = async (path) => {
+    if (!(await exists(path)))
+        return undefined;
+    const loaded = await readFile(path, 'utf8');
+    return dotenv.parse(loaded);
+};
+export const merge_envs = (envs, visibility, public_prefix, private_prefix) => {
+    const env = {};
+    for (const e of envs) {
+        for (const key in e) {
+            if ((visibility === 'private' && is_private_env(key, public_prefix, private_prefix)) ||
+                (visibility === 'public' && is_public_env(key, public_prefix, private_prefix))) {
+                const value = e[key];
+                if (value !== undefined)
+                    env[key] = value;
+            }
+        }
+    }
+    return env;
+};
+export const is_private_env = (key, public_prefix, private_prefix) => key.startsWith(private_prefix) && (public_prefix === '' || !key.startsWith(public_prefix));
+export const is_public_env = (key, public_prefix, private_prefix) => key.startsWith(public_prefix) && (private_prefix === '' || !key.startsWith(private_prefix));
+/**
+ * Loads a single env value without merging it into `process.env`.
+ * By default searches process.env, then a local `.env` if one exists, then `../.env` if it exists.
+ */
+export const load_from_env = async (key, paths = ['.env', '../.env']) => {
+    if (process.env[key])
+        return process.env[key];
+    for (const path of paths) {
+        const env = await load(path); // eslint-disable-line no-await-in-loop
+        if (env?.[key])
+            return env[key];
+    }
+    return undefined;
+};

package/dist/esbuild_helpers.d.ts

@@ -0,0 +1,14 @@
+import type * as esbuild from 'esbuild';
+import type { Parsed_Sveltekit_Config } from './sveltekit_config.js';
+export declare const print_build_result: (log: Logger, build_result: esbuild.BuildResult) => void;
+/**
+ * Creates an esbuild `define` shim for Vite's `import.meta\.env`.
+ * @see https://esbuild.github.io/api/#define
+ * @param dev
+ * @param base_url - best-effort shim from SvelteKit's `base` to Vite's `import.meta\.env.BASE_URL`
+ * @param ssr
+ * @param mode
+ * @returns
+ */
+export declare const to_define_import_meta_env: (dev: boolean, base_url: Parsed_Sveltekit_Config['base_url'], ssr?: boolean, mode?: string) => Record<string, string>;
+export declare const ts_transform_options: esbuild.TransformOptions;

package/dist/esbuild_helpers.js

@@ -0,0 +1,36 @@
+import { yellow, red } from 'kleur/colors';
+export const print_build_result = (log, build_result) => {
+    for (const error of build_result.errors) {
+        log.error(red('esbuild error'), error);
+    }
+    for (const warning of build_result.warnings) {
+        log.warn(yellow('esbuild warning'), warning);
+    }
+};
+// This concatenates weirdly to avoid a SvelteKit warning,
+// because SvelteKit detects usage as a string and not the AST.
+const import_meta_env = 'import.' + 'meta.env.'; // eslint-disable-line no-useless-concat
+/**
+ * Creates an esbuild `define` shim for Vite's `import.meta\.env`.
+ * @see https://esbuild.github.io/api/#define
+ * @param dev
+ * @param base_url - best-effort shim from SvelteKit's `base` to Vite's `import.meta\.env.BASE_URL`
+ * @param ssr
+ * @param mode
+ * @returns
+ */
+export const to_define_import_meta_env = (dev, base_url, ssr = true, mode = dev ? 'development' : 'production') => ({
+    // see `import_meta_env` for why this is defined weirdly instead of statically
+    [import_meta_env + 'DEV']: JSON.stringify(dev),
+    [import_meta_env + 'PROD']: JSON.stringify(!dev),
+    [import_meta_env + 'SSR']: JSON.stringify(ssr),
+    [import_meta_env + 'MODE']: JSON.stringify(mode),
+    [import_meta_env + 'BASE_URL']: JSON.stringify(base_url || '/'), // it appears SvelteKit's `''` translates to Vite's `'/'`, so this intentionally falls back for falsy values, not just undefined
+});
+export const ts_transform_options = {
+    target: 'esnext',
+    format: 'esm',
+    loader: 'ts',
+    charset: 'utf8',
+    // TODO load local tsconfig
+};

package/dist/esbuild_plugin_external_worker.d.ts

@@ -0,0 +1,22 @@
+/// <reference types="svelte" />
+import * as esbuild from 'esbuild';
+import type { Logger } from '@ryanatkn/belt/log.js';
+import type { CompileOptions, PreprocessorGroup } from 'svelte/compiler';
+import type { Parsed_Sveltekit_Config } from './sveltekit_config.js';
+export interface Options {
+    dev: boolean;
+    build_options: esbuild.BuildOptions;
+    dir?: string;
+    svelte_compile_options?: CompileOptions;
+    svelte_preprocessors?: PreprocessorGroup | PreprocessorGroup[];
+    alias?: Record<string, string>;
+    base_url?: Parsed_Sveltekit_Config['base_url'];
+    assets_url?: Parsed_Sveltekit_Config['assets_url'];
+    public_prefix?: string;
+    private_prefix?: string;
+    env_dir?: string;
+    env_files?: string[];
+    ambient_env?: Record<string, string>;
+    log?: Logger;
+}
+export declare const esbuild_plugin_external_worker: ({ dev, build_options, dir, svelte_compile_options, svelte_preprocessors, alias, base_url, assets_url, public_prefix, private_prefix, env_dir, env_files, ambient_env, log, }: Options) => esbuild.Plugin;