@nanobpm/urban 0.4.0 → 0.5.0

package/README.md

@@ -19,8 +19,10 @@ npx @nanobpm/urban new my-app
 deno run -A npm:@nanobpm/urban run
 ```
 
-Requires Node ≥ 22.6 or Deno. It ships as TypeScript source with no build step;
-on Node < 23.6 the `urban` command re-executes with `--experimental-strip-types`.
+Requires Node ≥ 22.6 or Deno. It ships as compiled JavaScript with `.d.ts` type
+declarations: Node can't strip types under `node_modules`, so the published package
+carries `dist/` and needs no build step or `--experimental-strip-types` flag to run.
+Deno users can still import the TypeScript source directly via the `./source` export.
 
 ## The `urban` CLI
 

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function main(argv: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,212 @@
+// The `urban` CLI — a thin command surface over the Urban runtime + toolkit.
+//
+//   urban new <name>     scaffold a new app (delegates to create-urban-app)
+//   urban check          load + validate the manifest, report issues
+//   urban gen            derive generated artifacts (migrations, worker I/O)
+//   urban run            materialize + serve the app (deploy, data, workers, surfaces, triggers)
+//   urban dev            like run (hot-reload is not yet implemented; documented below)
+//   urban deploy         deploy models only, then exit
+//
+// Global flags: --root <dir> (default "."), --manifest <file> (default nano.app.json),
+//               --port <n>, -h/--help, -v/--version.
+import { collectManifestIssues, loadManifest, runFromEnv, selectHost, } from "./runtime/index.js";
+import { scaffold, slugify } from "create-urban-app";
+import { createNodeGenIO, runGen } from "./toolkit/index.js";
+import { pathToFileURL } from "node:url";
+import { readFileSync } from "node:fs";
+// Read the package version from package.json (one hop up from both src/cli.ts and the
+// compiled dist/cli.js) so `urban --version` never drifts from the published version.
+function readVersion() {
+    try {
+        const url = new URL("../package.json", import.meta.url);
+        return JSON.parse(readFileSync(url, "utf8")).version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+const VERSION = readVersion();
+function parse(argv) {
+    const f = { root: ".", manifest: "nano.app.json", check: false, help: false, version: false, _: [] };
+    const need = (i, flag) => {
+        const v = argv[i];
+        if (v === undefined || v.startsWith("-"))
+            throw new Error(`flag ${flag} requires a value`);
+        return v;
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "-h" || a === "--help")
+            f.help = true;
+        else if (a === "-v" || a === "--version")
+            f.version = true;
+        else if (a === "--check")
+            f.check = true;
+        else if (a === "--root")
+            f.root = need(++i, a);
+        else if (a === "--manifest")
+            f.manifest = need(++i, a);
+        else if (a === "--port") {
+            const raw = need(++i, a);
+            const n = Number(raw);
+            if (!Number.isInteger(n) || n < 0 || n > 65535) {
+                throw new Error(`flag --port requires an integer in 0..65535 (got "${raw}")`);
+            }
+            f.port = n;
+        }
+        else if (a.startsWith("-"))
+            throw new Error(`unknown flag: ${a}`);
+        else
+            f._.push(a);
+    }
+    return f;
+}
+const USAGE = `urban — build and run Urban apps (nano.app.json)
+
+Usage:
+  urban new <name> [--root <path>]    scaffold a new Urban app
+  urban check                       validate the manifest
+  urban gen [--check]               derive artifacts (migrations, worker-io)
+  urban run                         materialize + serve the app
+  urban dev                         run (hot-reload not yet implemented)
+  urban deploy                      deploy models only, then exit
+
+Global flags:
+  --root <dir>        app root (default ".")
+  --manifest <file>   manifest filename (default "nano.app.json")
+  --port <n>          HTTP port for surfaces/triggers (default $PORT or 8090)
+  -h, --help          show this help
+  -v, --version       print version
+
+Engine address: $CAMUNDA_REST_ADDRESS (default http://localhost:8080/v2).
+`;
+async function cmdCheck(f) {
+    // The host is anchored at f.root, so manifest paths are already root-relative —
+    // pass the bare manifest filename (prefixing root again would double it).
+    const host = selectHost({ cwd: f.root });
+    const manifest = await loadManifest(host, f.manifest);
+    const issues = collectManifestIssues(manifest);
+    if (issues.length === 0) {
+        console.log(`✔ ${manifest.name ?? manifest.id} — manifest is valid`);
+        return 0;
+    }
+    console.error(`✖ ${issues.length} issue(s) in ${f.manifest}:`);
+    for (const it of issues)
+        console.error(`  • ${it.path}: ${it.message}`);
+    return 1;
+}
+async function cmdGen(f) {
+    const io = createNodeGenIO();
+    const res = await runGen({ root: f.root, io, manifestFile: f.manifest, check: f.check });
+    if (f.check) {
+        if (res.drift.length === 0) {
+            console.log(`✔ generated artifacts are up to date (${res.artifacts.length} checked)`);
+            return 0;
+        }
+        console.error(`✖ ${res.drift.length} generated artifact(s) are out of date — run \`urban gen\`:`);
+        for (const p of res.drift)
+            console.error(`  • ${p}`);
+        return 1;
+    }
+    console.log(`✔ generated ${res.artifacts.length} artifact(s):`);
+    for (const a of res.artifacts)
+        console.log(`  • ${a.path}`);
+    return 0;
+}
+async function cmdRun(f, mount) {
+    const app = await runFromEnv({
+        root: f.root,
+        manifestPath: f.manifest,
+        port: f.port,
+        mount,
+    });
+    const info = app.inspect();
+    console.log(`▲ ${info.name} — surfaces on :${info.httpPort ?? "n/a"} (Ctrl-C to stop)`);
+    return -1; // keep the process alive; signal handlers stop it
+}
+async function cmdDeploy(f) {
+    const app = await runFromEnv({
+        root: f.root,
+        manifestPath: f.manifest,
+        mount: { deploy: true, data: false, workers: false, surfaces: false, triggers: false, security: false },
+        handleSignals: false,
+    });
+    console.log(`✔ deployed models for ${app.manifest.name ?? app.manifest.id}`);
+    await app.stop();
+    return 0;
+}
+async function cmdNew(f) {
+    const name = f._[1];
+    if (!name) {
+        console.error("usage: urban new <name> [--root <path>]");
+        return 1;
+    }
+    const dir = f.root !== "." ? f.root : `./${slugify(name)}`;
+    const res = await scaffold({ name, dir });
+    console.log(`✔ scaffolded "${res.id}" in ${res.dir} (${res.files.length} files)`);
+    console.log(`  cd ${res.dir} && (npm install && npm start) || deno task start`);
+    return 0;
+}
+export async function main(argv) {
+    let f;
+    try {
+        f = parse(argv);
+    }
+    catch (err) {
+        console.error(String(err.message));
+        return 1;
+    }
+    if (f.version) {
+        console.log(VERSION);
+        return 0;
+    }
+    const cmd = f._[0];
+    if (f.help || !cmd) {
+        console.log(USAGE);
+        return cmd ? 0 : f.help ? 0 : 1;
+    }
+    switch (cmd) {
+        case "new":
+        case "scaffold":
+            return cmdNew(f);
+        case "check":
+            return cmdCheck(f);
+        case "gen":
+            return cmdGen(f);
+        case "run":
+            return cmdRun(f);
+        case "dev":
+            console.log("urban dev: hot-reload is not yet implemented; running once.");
+            return cmdRun(f);
+        case "deploy":
+            return cmdDeploy(f);
+        default:
+            console.error(`unknown command: ${cmd}\n`);
+            console.log(USAGE);
+            return 1;
+    }
+}
+const g = globalThis;
+const meta = import.meta;
+const argv1 = g.process?.argv?.[1];
+const nodeMain = argv1 ? meta.url === pathToFileURL(argv1).href : false;
+if (meta.main === true || nodeMain) {
+    // Node passes args via process.argv (slice off exec+script); Deno (run directly)
+    // exposes them on Deno.args. Prefer whichever actually carries args.
+    const fromNode = g.process?.argv?.slice(2);
+    const fromDeno = g.Deno?.args;
+    const argv = (fromNode && fromNode.length ? fromNode : fromDeno) ?? fromNode ?? [];
+    const exit = (code) => {
+        if (g.process?.exit)
+            g.process.exit(code);
+        else if (g.Deno?.exit)
+            g.Deno.exit(code);
+    };
+    main(argv).then((code) => {
+        if (code >= 0)
+            exit(code);
+    }, (err) => {
+        console.error(String(err?.message ?? err));
+        exit(1);
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./runtime/index.ts";
+export { createCamundaClient } from "@nanobpm/nano-sdk";
+export * from "./toolkit/index.ts";
+export { defineFlow, declarativeToBpmn, declarativeToLayoutedBpmn, externalJobTypes, envelope, layoutBpmn, toBpmn, toDeployableBpmn, Worker, WorkflowClient, WorkflowError, } from "@nanobpm/workflow";
+export type { FlowBuilder, Envelope, EnvelopeType, EnvelopeField, FieldSpec, ScalarType, WorkflowClientOptions, NanoSdkClient, NanoJobWorker, JobWorkerConfig, ActivatedJob, WorkerOptions, ActivityEvent, } from "@nanobpm/workflow";

package/dist/index.js

@@ -0,0 +1,25 @@
+// @nanobpm/urban — the code-first Urban stack in one package (ADR 0054):
+//
+//   • runtime — materialize and serve an app from a nano.app.json manifest
+//     (datasource, workers, surfaces, triggers) on Node or Deno.
+//   • toolkit — pure derivers (`urban gen`) that emit generated artifacts
+//     (SQL migrations, worker I/O bindings) from the model.
+//   • workflow — the code-first process surface, re-exported from
+//     `@nanobpm/workflow`: author durable flows with `defineFlow` and the SDK
+//     derives the executable BPMN, job types, and correlation wiring.
+//
+// The CLI (`urban`) is a separate entrypoint (bin) over this same API.
+// Subpath imports are also available: `@nanobpm/urban/runtime` and
+// `@nanobpm/urban/toolkit`.
+// Runtime — app materialization + hosting
+export * from "./runtime/index.js";
+// The nano-sdk engine client factory: build a client to talk to a Nano/Camunda
+// engine directly, or type an `AppApi.sdk`. The runtime uses this same factory, so a
+// code-first author reaches the full engine surface without a separate
+// `@nanobpm/nano-sdk` dependency. (`EngineSdkClient`, its return type, is re-exported
+// from ./runtime/index.ts above.)
+export { createCamundaClient } from "@nanobpm/nano-sdk";
+// Toolkit — derivation library (`urban gen`)
+export * from "./toolkit/index.js";
+// Code-first process surface (re-exported from @nanobpm/workflow)
+export { defineFlow, declarativeToBpmn, declarativeToLayoutedBpmn, externalJobTypes, envelope, layoutBpmn, toBpmn, toDeployableBpmn, Worker, WorkflowClient, WorkflowError, } from "@nanobpm/workflow";

package/dist/runtime/adapters/deno.d.ts

@@ -0,0 +1,6 @@
+import type { HostContext } from "../core/host.ts";
+export interface DenoHostOptions {
+    cwd?: string;
+    log?: HostContext["log"];
+}
+export declare function createDenoHost(opts?: DenoHostOptions): HostContext;

package/dist/runtime/adapters/deno.js

@@ -0,0 +1,98 @@
+// Deno adapter — implements HostContext against the `Deno` global (plus `node:*` compat
+// modules Deno supports). This and node.ts are the only files that touch a concrete runtime.
+// A minimal ambient `Deno` declaration lets this compile under Node's tsc; at runtime the
+// adapter is only ever selected when the real `Deno` global is present (see detect.ts).
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { DatabaseSync } from "node:sqlite";
+export function createDenoHost(opts = {}) {
+    const cwd = opts.cwd ?? Deno.cwd();
+    const abs = (p) => (isAbsolute(p) ? p : resolve(cwd, p));
+    const log = opts.log ??
+        ((level, msg, fields) => {
+            const line = fields ? `${msg} ${JSON.stringify(fields)}` : msg;
+            (level === "error" ? console.error : level === "warn" ? console.warn : console.log)(`[urban] ${line}`);
+        });
+    return {
+        runtime: "deno",
+        env: (name) => Deno.env.get(name),
+        readTextFile: (p) => Deno.readTextFile(abs(p)),
+        async listDir(dir) {
+            try {
+                const names = [];
+                for await (const e of Deno.readDir(abs(dir))) {
+                    if (e.isFile)
+                        names.push(e.name);
+                }
+                return names;
+            }
+            catch {
+                return [];
+            }
+        },
+        async exists(p) {
+            try {
+                await Deno.stat(abs(p));
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        openSqlite(path) {
+            const db = new DatabaseSync(abs(path));
+            return wrapSqlite(db);
+        },
+        importModule: (p) => import(__rewriteRelativeImportExtension(pathToFileURL(abs(p)).href)),
+        async serveHttp(port, handler) {
+            return startDenoServer(port, handler);
+        },
+        now: () => Date.now(),
+        log,
+    };
+}
+function wrapSqlite(db) {
+    return {
+        exec: (sql) => db.exec(sql),
+        run: (sql, params = []) => {
+            const stmt = db.prepare(sql);
+            const r = stmt.run(...params);
+            return { changes: Number(r.changes), lastInsertRowid: r.lastInsertRowid };
+        },
+        all: (sql, params = []) => {
+            const stmt = db.prepare(sql);
+            return stmt.all(...params);
+        },
+        close: () => db.close(),
+    };
+}
+function startDenoServer(port, handler) {
+    return new Promise((resolveServer) => {
+        const server = Deno.serve({ port, onListen: ({ port: p }) => {
+                resolveServer({
+                    port: p,
+                    stop: () => server.shutdown(),
+                });
+            } }, async (request) => {
+            const url = new URL(request.url);
+            const bodyText = request.body ? await request.text() : "";
+            const req = {
+                method: request.method,
+                path: url.pathname,
+                query: url.searchParams,
+                headers: request.headers,
+                text: () => Promise.resolve(bodyText),
+            };
+            const res = await handler(req);
+            return new Response(res.body ?? "", { status: res.status ?? 200, headers: res.headers });
+        });
+    });
+}

package/dist/runtime/adapters/detect.d.ts

@@ -0,0 +1,9 @@
+import type { HostContext } from "../core/host.ts";
+/** True when running under Deno. */
+export declare function isDeno(): boolean;
+export interface SelectHostOptions {
+    cwd?: string;
+    log?: HostContext["log"];
+}
+/** Select and construct the host for the current runtime. */
+export declare function selectHost(opts?: SelectHostOptions): HostContext;

package/dist/runtime/adapters/detect.js

@@ -0,0 +1,13 @@
+// Runtime detection: pick the Node or Deno host at load time. Importing both adapter
+// modules is safe — neither touches its runtime's globals at module top level.
+import { createNodeHost } from "./node.js";
+import { createDenoHost } from "./deno.js";
+/** True when running under Deno. */
+export function isDeno() {
+    const g = globalThis;
+    return typeof g.Deno !== "undefined" && typeof g.Deno.version !== "undefined";
+}
+/** Select and construct the host for the current runtime. */
+export function selectHost(opts = {}) {
+    return isDeno() ? createDenoHost(opts) : createNodeHost(opts);
+}

package/dist/runtime/adapters/node.d.ts

@@ -0,0 +1,7 @@
+import type { HostContext } from "../core/host.ts";
+export interface NodeHostOptions {
+    /** Base directory relative paths resolve against. Default process.cwd(). */
+    cwd?: string;
+    log?: HostContext["log"];
+}
+export declare function createNodeHost(opts?: NodeHostOptions): HostContext;

package/dist/runtime/adapters/node.js

@@ -0,0 +1,113 @@
+// Node adapter — implements HostContext against `node:*`. This is one of only two files
+// (with deno.ts) allowed to touch a concrete runtime.
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { readFile, readdir, stat } from "node:fs/promises";
+import { createServer } from "node:http";
+import { isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { DatabaseSync } from "node:sqlite";
+export function createNodeHost(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const abs = (p) => (isAbsolute(p) ? p : resolve(cwd, p));
+    const log = opts.log ??
+        ((level, msg, fields) => {
+            const line = fields ? `${msg} ${JSON.stringify(fields)}` : msg;
+            (level === "error" ? console.error : level === "warn" ? console.warn : console.log)(`[urban] ${line}`);
+        });
+    return {
+        runtime: "node",
+        env: (name) => process.env[name],
+        readTextFile: (p) => readFile(abs(p), "utf8"),
+        async listDir(dir) {
+            try {
+                const entries = await readdir(abs(dir), { withFileTypes: true });
+                return entries.filter((e) => e.isFile()).map((e) => e.name);
+            }
+            catch {
+                return [];
+            }
+        },
+        async exists(p) {
+            try {
+                await stat(abs(p));
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        openSqlite(path) {
+            const db = new DatabaseSync(abs(path));
+            return wrapNodeSqlite(db);
+        },
+        importModule: (p) => import(__rewriteRelativeImportExtension(pathToFileURL(abs(p)).href)),
+        async serveHttp(port, handler) {
+            return await startNodeServer(port, handler);
+        },
+        now: () => Date.now(),
+        log,
+    };
+}
+function wrapNodeSqlite(db) {
+    return {
+        exec: (sql) => db.exec(sql),
+        run: (sql, params = []) => {
+            const stmt = db.prepare(sql);
+            const r = stmt.run(...params);
+            return { changes: Number(r.changes), lastInsertRowid: r.lastInsertRowid };
+        },
+        all: (sql, params = []) => {
+            const stmt = db.prepare(sql);
+            return stmt.all(...params);
+        },
+        close: () => db.close(),
+    };
+}
+async function startNodeServer(port, handler) {
+    const server = createServer(async (nreq, nres) => {
+        const chunks = [];
+        for await (const c of nreq)
+            chunks.push(c);
+        const bodyText = Buffer.concat(chunks).toString("utf8");
+        const url = new URL(nreq.url ?? "/", "http://localhost");
+        const headers = new Headers();
+        for (const [k, v] of Object.entries(nreq.headers)) {
+            if (typeof v === "string")
+                headers.set(k, v);
+            else if (Array.isArray(v))
+                headers.set(k, v.join(", "));
+        }
+        const req = {
+            method: nreq.method ?? "GET",
+            path: url.pathname,
+            query: url.searchParams,
+            headers,
+            text: () => Promise.resolve(bodyText),
+        };
+        try {
+            const res = await handler(req);
+            nres.statusCode = res.status ?? 200;
+            for (const [k, v] of Object.entries(res.headers ?? {}))
+                nres.setHeader(k, v);
+            nres.end(res.body ?? "");
+        }
+        catch (err) {
+            nres.statusCode = 500;
+            nres.end(String(err));
+        }
+    });
+    await new Promise((res) => server.listen(port, res));
+    const addr = server.address();
+    const actualPort = typeof addr === "object" && addr ? addr.port : port;
+    return {
+        port: actualPort,
+        stop: () => new Promise((res) => server.close(() => res())),
+    };
+}

package/dist/runtime/core/context.d.ts

@@ -0,0 +1,40 @@
+import type { AppManifest } from "./manifest.ts";
+import type { EngineClient, HostContext } from "./host.ts";
+import type { EngineSdkClient } from "../engine/sdk.ts";
+/** Everything a runtime module needs. Passed to each module's mount function. */
+export interface RuntimeContext {
+    manifest: AppManifest;
+    host: HostContext;
+    engine: EngineClient;
+    /** App root directory (paths in the manifest are relative to this). */
+    root: string;
+}
+/** A mounted module returns a disposer so the runtime can tear it down cleanly. */
+export interface Mounted {
+    readonly name: string;
+    stop(): Promise<void>;
+    /** Optional human-readable summary for `inspect()`. */
+    describe?(): Record<string, unknown>;
+}
+import type { DataLayer } from "./modules/datasource.ts";
+/**
+ * The surface injected into worker/trigger/surface handlers — the app's runtime API.
+ * This is how a handler reaches the datasource (typed accessors), the engine, and host
+ * utilities without hard-coding any of them.
+ */
+export interface AppApi {
+    manifest: AppManifest;
+    data: DataLayer;
+    engine: EngineClient;
+    /**
+     * The underlying `@nanobpm/nano-sdk` engine client, present when the app runs on
+     * the nano-sdk transport (the default). It exposes the full Camunda
+     * orchestration-cluster surface — decisions, cluster variables, incidents, user
+     * tasks, agents, batch operations — beyond the transport-agnostic `engine` seam,
+     * over the same connection. Undefined when a non-SDK engine is injected (e.g. an
+     * in-memory test double).
+     */
+    sdk?: EngineSdkClient;
+    env(name: string): string | undefined;
+    log(level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>): void;
+}

package/dist/runtime/core/context.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/core/glob.d.ts

@@ -0,0 +1,5 @@
+import type { HostContext } from "./host.ts";
+/** Expand a single pattern (relative to `root`) to a sorted list of matching file paths. */
+export declare function expandPattern(host: HostContext, root: string, pattern: string): Promise<string[]>;
+/** Expand many patterns, de-duplicating while preserving first-seen order. */
+export declare function expandPatterns(host: HostContext, root: string, patterns: string[] | undefined): Promise<string[]>;

package/dist/runtime/core/glob.js

@@ -0,0 +1,51 @@
+// A deliberately tiny glob: resolves patterns of the form "dir/*.ext" (a single directory
+// plus a `*.ext` or `*` leaf) against the host filesystem. This covers the manifest
+// `models` patterns (e.g. "processes/*.bpmn") without pulling in a glob dependency, keeping
+// core runtime-agnostic. A literal path (no `*`) resolves to itself if it exists.
+function joinPath(a, b) {
+    if (!a)
+        return b;
+    return `${a.replace(/\/+$/, "")}/${b.replace(/^\/+/, "")}`;
+}
+/** Expand a single pattern (relative to `root`) to a sorted list of matching file paths. */
+export async function expandPattern(host, root, pattern) {
+    if (!pattern.includes("*")) {
+        const p = joinPath(root, pattern);
+        return (await host.exists(p)) ? [p] : [];
+    }
+    const slash = pattern.lastIndexOf("/");
+    const dirPart = slash >= 0 ? pattern.slice(0, slash) : "";
+    const leaf = slash >= 0 ? pattern.slice(slash + 1) : pattern;
+    const dir = joinPath(root, dirPart);
+    let re;
+    if (leaf === "*") {
+        re = /.*/;
+    }
+    else if (leaf.startsWith("*.")) {
+        const ext = leaf.slice(1); // ".bpmn"
+        re = new RegExp(`${ext.replace(/[.]/g, "\\.")}$`);
+    }
+    else {
+        // Fall back to translating a simple leaf glob (`*` → `.*`).
+        re = new RegExp(`^${leaf.replace(/[.]/g, "\\.").replace(/\*/g, ".*")}$`);
+    }
+    const names = await host.listDir(dir);
+    return names
+        .filter((n) => re.test(n))
+        .sort()
+        .map((n) => joinPath(dir, n));
+}
+/** Expand many patterns, de-duplicating while preserving first-seen order. */
+export async function expandPatterns(host, root, patterns) {
+    const seen = new Set();
+    const out = [];
+    for (const pat of patterns ?? []) {
+        for (const p of await expandPattern(host, root, pat)) {
+            if (!seen.has(p)) {
+                seen.add(p);
+                out.push(p);
+            }
+        }
+    }
+    return out;
+}