@rivetjs/nx 0.0.0-stage → 0.1.0-alpha.1

package/utils/project.js

@@ -0,0 +1,67 @@
+// The Rivet project a generator targets (`--project`).
+import { joinPathFragments, readProjectConfiguration } from "@nx/devkit";
+import { treeFacts } from "./facts.js";
+export function rivetProject(tree, name) {
+    const config = readProjectConfiguration(tree, name);
+    const root = config.root;
+    const src = config.sourceRoot ?? joinPathFragments(root, "src");
+    const facts = treeFacts(tree, root);
+    const library = config.projectType === "library" || (facts?.kind ?? "lib") === "lib";
+    return { name, root, src, routes: joinPathFragments(src, "routes"), facts, library };
+}
+/** Throws unless the project is a file-routed Rivet app (`rivetRouter()` in its Vite config). */
+export function routedApp(tree, name, generator) {
+    const project = rivetProject(tree, name);
+    if (project.facts?.kind !== "app")
+        throw new Error(`${generator}: ${name} is not a Rivet app with file routes (no rivetRouter() in its vite.config)`);
+    return project;
+}
+/** Route path → segments: `blog/[slug]` → `["blog", "[slug]"]` (leading `/`, `src/routes/`, extension and `index` dropped). */
+export function routeSegments(path) {
+    const clean = path
+        .replace(/\\/g, "/")
+        .replace(/^\/+|\/+$/g, "")
+        .replace(/^src\/routes\//, "")
+        .replace(/\.(tsx|ts|jsx|js)$/, "");
+    const segments = clean.split("/").filter(Boolean);
+    if (segments.at(-1) === "index")
+        segments.pop();
+    for (const segment of segments) {
+        if (!/^(\[\[[A-Za-z_$][\w$]*\]\]|\[(\.\.\.)?[A-Za-z_$][\w$]*\]|\([\w-]+\)|[\w.-]+)$/.test(segment))
+            throw new Error(`Invalid route segment "${segment}" (use name, [param], [[optional]], [...rest] or (group))`);
+    }
+    return segments;
+}
+export function routeParams(segments) {
+    return segments.flatMap((segment) => {
+        const optional = /^\[\[(.+)\]\]$/.exec(segment);
+        if (optional)
+            return [{ name: optional[1], kind: "optional" }];
+        const rest = /^\[\.\.\.(.+)\]$/.exec(segment);
+        if (rest)
+            return [{ name: rest[1], kind: "rest" }];
+        const one = /^\[(.+)\]$/.exec(segment);
+        return one ? [{ name: one[1], kind: "one" }] : [];
+    });
+}
+/** `PascalCase` name of route segments (`blog/[slug]` → `BlogSlug`; root → `Home`). */
+export function routeComponentName(segments) {
+    const words = segments
+        .map((segment) => segment.replace(/[[\]().]/g, " "))
+        .join(" ")
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean);
+    const name = words.map((word) => word[0].toUpperCase() + word.slice(1)).join("");
+    return name && /^[A-Za-z]/.test(name) ? name : "Home";
+}
+/** `../` from a file in `dir` (workspace-relative) back to `to`. */
+export function relativeImport(fromDir, to) {
+    const from = fromDir.split("/").filter(Boolean);
+    const target = to.split("/").filter(Boolean);
+    let common = 0;
+    while (common < from.length && common < target.length - 1 && from[common] === target[common])
+        common++;
+    const up = from.length - common;
+    const rel = [...Array.from({ length: up }, () => ".."), ...target.slice(common)].join("/");
+    return rel.startsWith(".") ? rel : "./" + rel;
+}

package/utils/starter.d.ts

@@ -0,0 +1,9 @@
+import type { Tree } from "@nx/devkit";
+import { TEMPLATES, type PackageJson, type TemplateId } from "create-rivet";
+export { TEMPLATES, type PackageJson, type TemplateId };
+/** The folder (`starter-static`, …) of a template id. */
+export declare function starterDir(template: TemplateId): string;
+/** Writes a starter's files under `root` (package.json rewritten: `name`, `@rivetjs/*` → `range`). Returns the paths written. */
+export declare function writeStarter(tree: Tree, template: TemplateId, root: string, name: string, range: string): string[];
+/** One file of a starter (`serve.js` of `starter-server`, …). */
+export declare function starterFile(template: TemplateId, path: string): Buffer;

package/utils/starter.js

@@ -0,0 +1,34 @@
+// Starter templates in an Nx tree: the same files create-rivet copies (the repository's `templates/`, bundled into
+// the create-rivet package), read through create-rivet's own helpers — no starter file is duplicated here.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { findTemplate, rewriteManifest, templateFiles, templatesRoot, TEMPLATES } from "create-rivet";
+export { TEMPLATES };
+/** The folder (`starter-static`, …) of a template id. */
+export function starterDir(template) {
+    const found = findTemplate(template);
+    if (!found)
+        throw new Error(`Unknown template "${template}" (${TEMPLATES.map((t) => t.id).join(", ")})`);
+    return found.dir;
+}
+/** Writes a starter's files under `root` (package.json rewritten: `name`, `@rivetjs/*` → `range`). Returns the paths written. */
+export function writeStarter(tree, template, root, name, range) {
+    const source = join(templatesRoot(), starterDir(template));
+    const written = [];
+    for (const file of templateFiles(source)) {
+        const target = join(root, file.path);
+        if (file.path === "package.json") {
+            const pkg = rewriteManifest(JSON.parse(readFileSync(file.source, "utf8")), name, range);
+            tree.write(target, JSON.stringify(pkg, null, 2) + "\n");
+        }
+        else {
+            tree.write(target, readFileSync(file.source));
+        }
+        written.push(file.path);
+    }
+    return written;
+}
+/** One file of a starter (`serve.js` of `starter-server`, …). */
+export function starterFile(template, path) {
+    return readFileSync(join(templatesRoot(), starterDir(template), path));
+}

package/utils/targets.d.ts

@@ -0,0 +1,22 @@
+import type { TargetConfiguration } from "@nx/devkit";
+import type { ProjectFacts } from "./detect.js";
+/** Target names (plugin options in nx.json: `{ "plugin": "@rivetjs/nx/plugin", "options": { "buildTargetName": "bundle" } }`). */
+export interface RivetPluginOptions {
+    buildTargetName?: string;
+    devTargetName?: string;
+    previewTargetName?: string;
+    testTargetName?: string;
+    checkTargetName?: string;
+    typecheckTargetName?: string;
+    /** Platform deploy (vercel / cloudflare adapters). */
+    deployTargetName?: string;
+}
+export declare const DEFAULT_TARGET_NAMES: Required<RivetPluginOptions>;
+export declare function targetNames(options: RivetPluginOptions | undefined): Required<RivetPluginOptions>;
+/**
+ * The targets of a project. `production`: whether nx.json defines a `production` named input (then build inputs
+ * use it, as official plugins do); otherwise `default` minus test files.
+ */
+export declare function rivetTargets(facts: ProjectFacts, options?: RivetPluginOptions, { production }?: {
+    production?: boolean | undefined;
+}): Record<string, TargetConfiguration>;

package/utils/targets.js

@@ -0,0 +1,117 @@
+import { deployOutputs, deployScripts } from "./deploy.js";
+export const DEFAULT_TARGET_NAMES = {
+    buildTargetName: "build",
+    devTargetName: "dev",
+    previewTargetName: "preview",
+    testTargetName: "test",
+    checkTargetName: "check",
+    typecheckTargetName: "typecheck",
+    deployTargetName: "deploy",
+};
+export function targetNames(options) {
+    const out = { ...DEFAULT_TARGET_NAMES };
+    for (const key of Object.keys(out)) {
+        const value = options?.[key];
+        if (typeof value === "string" && value)
+            out[key] = value;
+    }
+    return out;
+}
+/** Generated / output folders: never inputs (the build writes `.rivet/`, which would otherwise bust its own cache). */
+const NOT_SOURCES = [
+    "!{projectRoot}/.rivet/**/*",
+    "!{projectRoot}/dist/**/*",
+    "!{projectRoot}/coverage/**/*",
+    "!{projectRoot}/src/rivet-i18n.d.ts",
+    // Platform packaging output / CLI state (`rivetRouter({ adapter })`).
+    "!{projectRoot}/.vercel/**/*",
+    "!{projectRoot}/.netlify/**/*",
+    "!{projectRoot}/.wrangler/**/*",
+];
+/** Test files are not inputs of build-like targets (Nx `production` convention). */
+const NOT_TESTS = ["!{projectRoot}/**/*.test.{ts,tsx}", "!{projectRoot}/**/*.spec.{ts,tsx}", "!{projectRoot}/vitest.config.{ts,mts,js,mjs}"];
+const tech = (description) => ({ technologies: ["rivet", "vite"], description });
+/**
+ * The targets of a project. `production`: whether nx.json defines a `production` named input (then build inputs
+ * use it, as official plugins do); otherwise `default` minus test files.
+ */
+export function rivetTargets(facts, options, { production = false } = {}) {
+    const names = targetNames(options);
+    const source = production ? ["production", "^production"] : ["default", "^default", ...NOT_TESTS];
+    const targets = {};
+    if (facts.kind !== "lib") {
+        const buildOptions = {};
+        if (facts.locales)
+            buildOptions["locales"] = facts.locales;
+        targets[names.buildTargetName] = {
+            executor: "@rivetjs/nx:build",
+            options: buildOptions,
+            cache: true,
+            dependsOn: ["^build"],
+            inputs: [...source, ...NOT_SOURCES],
+            outputs: ["{projectRoot}/dist", ...deployOutputs(facts.adapter)],
+            metadata: tech(facts.static ? "Client + server build, then prerender every page (static mode)" : facts.csr ? "Browser build (csr mode)" : "Client + server build"),
+        };
+        targets[names.devTargetName] = {
+            executor: "@rivetjs/nx:dev",
+            continuous: true,
+            options: {},
+            metadata: tech("Vite dev server (pages resume like production; hot reload)"),
+        };
+        // Platform adapters: create-rivet's `--deploy` scripts (same commands), run from the project folder.
+        const scripts = deployScripts(facts.adapter);
+        const platformPreview = scripts["preview"] ?? scripts["start"];
+        targets[names.previewTargetName] = platformPreview
+            ? {
+                executor: "nx:run-commands",
+                continuous: true,
+                dependsOn: [names.buildTargetName],
+                options: { command: platformPreview, cwd: "{projectRoot}" },
+                metadata: tech(`Serve the ${facts.adapter} build locally (${platformPreview})`),
+            }
+            : {
+                executor: "@rivetjs/nx:preview",
+                continuous: true,
+                dependsOn: [names.buildTargetName],
+                options: {},
+                metadata: tech(facts.serveScript ? "Serve the build with the project's serve.js" : "Serve the build"),
+            };
+        if (scripts["deploy"])
+            targets[names.deployTargetName] = {
+                executor: "nx:run-commands",
+                dependsOn: [names.buildTargetName],
+                options: { command: scripts["deploy"], cwd: "{projectRoot}" },
+                metadata: tech(`Deploy the build to ${facts.adapter} (${scripts["deploy"]})`),
+            };
+    }
+    if (facts.test) {
+        targets[names.testTargetName] = {
+            executor: "@rivetjs/nx:test",
+            options: {},
+            cache: true,
+            inputs: ["default", production ? "^production" : "^default", ...NOT_SOURCES],
+            outputs: ["{projectRoot}/coverage"],
+            metadata: { technologies: ["rivet", "vitest"], description: "Vitest with rivetTest() (DOM + server targets)" },
+        };
+    }
+    if (facts.tsconfig) {
+        const typeInputs = ["default", production ? "^production" : "^default", ...NOT_SOURCES];
+        targets[names.checkTargetName] = {
+            executor: "@rivetjs/nx:check",
+            options: {},
+            cache: true,
+            inputs: typeInputs,
+            outputs: [],
+            metadata: tech("Rivet diagnostics (rivet-check: compiler + serializability + route links)"),
+        };
+        targets[names.typecheckTargetName] = {
+            executor: "@rivetjs/nx:typecheck",
+            options: {},
+            cache: true,
+            inputs: typeInputs,
+            outputs: [],
+            metadata: { technologies: ["rivet", "typescript"], description: "tsc --noEmit (after rivet sync for routed apps)" },
+        };
+    }
+    return targets;
+}

package/utils/versions.d.ts

@@ -0,0 +1,13 @@
+/** This package's version (= every `@rivetjs/*` package of the same release). */
+export declare const RIVET_NX_VERSION: string;
+/** The `@nx/devkit` version this plugin is built against. */
+export declare const NX_VERSION: string;
+/** The range written for `@rivetjs/*` dependencies (`--rivetVersion` overrides): exact for prereleases, `^x.y.z` otherwise. */
+export declare function rivetRange(override?: string): string;
+/** Test tooling ranges = `@rivetjs/testing` peer ranges (`tests/versions.test.ts` keeps them in sync). */
+export declare const VITEST_VERSION = "^5.0.3";
+export declare const HAPPY_DOM_VERSION = "^20.14.5";
+/** Dependency ranges of a starter template's package.json (`starter-static`, …): the single source for tool versions. */
+export declare function starterVersions(dir?: string): Record<string, string>;
+/** A tool range from the starters (`vite`, `typescript`, `tailwindcss`, …). Throws when no starter names it. */
+export declare function toolVersion(name: string): string;

package/utils/versions.js

@@ -0,0 +1,31 @@
+// Versions written into generated projects. `@rivetjs/*` follow this package's own version (every Rivet package is
+// released with the same version, like create-rivet); tool ranges come from the starter templates where they exist.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { templatesRoot, versionRange } from "create-rivet";
+const own = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+/** This package's version (= every `@rivetjs/*` package of the same release). */
+export const RIVET_NX_VERSION = own.version;
+/** The `@nx/devkit` version this plugin is built against. */
+export const NX_VERSION = own.dependencies?.["@nx/devkit"] ?? "23.2.1";
+/** The range written for `@rivetjs/*` dependencies (`--rivetVersion` overrides): exact for prereleases, `^x.y.z` otherwise. */
+export function rivetRange(override) {
+    return override || versionRange(RIVET_NX_VERSION);
+}
+/** Test tooling ranges = `@rivetjs/testing` peer ranges (`tests/versions.test.ts` keeps them in sync). */
+export const VITEST_VERSION = "^5.0.3";
+export const HAPPY_DOM_VERSION = "^20.14.5";
+/** Dependency ranges of a starter template's package.json (`starter-static`, …): the single source for tool versions. */
+export function starterVersions(dir = "starter-static") {
+    const pkg = JSON.parse(readFileSync(join(templatesRoot(), dir, "package.json"), "utf8"));
+    return { ...pkg.dependencies, ...pkg.devDependencies };
+}
+/** A tool range from the starters (`vite`, `typescript`, `tailwindcss`, …). Throws when no starter names it. */
+export function toolVersion(name) {
+    for (const dir of ["starter-static", "starter-ui", "starter-server", "starter-minimal"]) {
+        const range = starterVersions(dir)[name];
+        if (range && !name.startsWith("@rivetjs/"))
+            return range;
+    }
+    throw new Error(`@rivetjs/nx: no starter template names a version of ${name}`);
+}

package/utils/vite-config.d.ts

@@ -0,0 +1,8 @@
+/** Adds `line` after the last top-level import (or at the top). No-op when already present. */
+export declare function addImport(source: string, line: string): string;
+/** Adds a plugin call (`i18n(config)`) first or last in `plugins`. No-op when the call name is already there. */
+export declare function addPlugin(source: string, call: string, position?: "first" | "last"): string;
+/** Removes a plugin call (`tailwindcss()`) from `plugins` and the import line matching `importPattern`. */
+export declare function removePlugin(source: string, call: string, importPattern: RegExp): string;
+/** Sets (`value` string) or removes (`undefined`) a top-level option of `rivetRouter({ … })` (`mode`, `styles`). */
+export declare function setRouterOption(source: string, key: string, value: string | undefined): string;

package/utils/vite-config.js

@@ -0,0 +1,104 @@
+// Text edits of a Vite config (`plugins: [ … ]`, `rivetRouter({ … })`). Configs written by the starters and the
+// generators have one `defineConfig({ plugins: [...] })`; edits are idempotent and throw on shapes they cannot edit.
+/** Adds `line` after the last top-level import (or at the top). No-op when already present. */
+export function addImport(source, line) {
+    if (source.includes(line))
+        return source;
+    const imports = [...source.matchAll(/^import[^;]*;[^\n]*\n/gm)];
+    const last = imports.at(-1);
+    if (!last)
+        return line + "\n" + source;
+    const at = last.index + last[0].length;
+    return source.slice(0, at) + line + "\n" + source.slice(at);
+}
+/** Index just inside the `[` of `plugins: [` and of its matching `]`. */
+function pluginsArray(source) {
+    const match = /\bplugins\s*:\s*\[/.exec(source);
+    if (!match)
+        throw new Error("vite config: no `plugins: [ … ]` array to edit");
+    const open = match.index + match[0].length;
+    let depth = 1;
+    for (let i = open; i < source.length; i++) {
+        const char = source[i];
+        if (char === "[" || char === "(" || char === "{")
+            depth++;
+        else if (char === "]" || char === ")" || char === "}") {
+            depth--;
+            if (depth === 0)
+                return { open, close: i };
+        }
+    }
+    throw new Error("vite config: unbalanced `plugins` array");
+}
+/** Adds a plugin call (`i18n(config)`) first or last in `plugins`. No-op when the call name is already there. */
+export function addPlugin(source, call, position = "last") {
+    const { open, close } = pluginsArray(source);
+    const name = call.slice(0, call.indexOf("("));
+    const list = source.slice(open, close);
+    if (new RegExp(`\\b${name}\\s*\\(`).test(list))
+        return source;
+    if (!list.trim())
+        return source.slice(0, open) + call + source.slice(close);
+    if (position === "first")
+        return source.slice(0, open) + call + ", " + source.slice(open);
+    const trimmed = list.replace(/[\s,]*$/, "");
+    return source.slice(0, open) + trimmed + ", " + call + source.slice(open + list.length);
+}
+/** Removes a plugin call (`tailwindcss()`) from `plugins` and the import line matching `importPattern`. */
+export function removePlugin(source, call, importPattern) {
+    const { open, close } = pluginsArray(source);
+    const list = source.slice(open, close);
+    const escaped = call.replace(/[()]/g, "\\$&");
+    const next = list.replace(new RegExp(`\\s*,\\s*${escaped}|${escaped}\\s*,\\s*|${escaped}`), "");
+    return (source.slice(0, open) + next + source.slice(close)).replace(new RegExp(`^.*${importPattern.source}.*\\n`, "m"), "");
+}
+/** Start / end (exclusive, at `)`) of the first `rivetRouter(` call's argument text. */
+function routerCall(source) {
+    const match = /\brivetRouter\s*\(/.exec(source);
+    if (!match)
+        throw new Error("vite config: no rivetRouter( … ) call to edit");
+    const start = match.index + match[0].length;
+    let depth = 1;
+    for (let i = start; i < source.length; i++) {
+        const char = source[i];
+        if (char === "(" || char === "[" || char === "{")
+            depth++;
+        else if (char === ")" || char === "]" || char === "}") {
+            depth--;
+            if (depth === 0)
+                return { start, end: i };
+        }
+    }
+    throw new Error("vite config: unbalanced rivetRouter( … ) call");
+}
+/** Sets (`value` string) or removes (`undefined`) a top-level option of `rivetRouter({ … })` (`mode`, `styles`). */
+export function setRouterOption(source, key, value) {
+    const { start, end } = routerCall(source);
+    let args = source.slice(start, end).trim();
+    if (!args)
+        args = "{}";
+    if (!args.startsWith("{"))
+        throw new Error("vite config: rivetRouter( … ) argument is not an object literal");
+    const inner = args.slice(1, -1);
+    // Top-level `key: value` inside the object (values here are literals / arrays: no nested commas outside brackets).
+    const entries = [];
+    let depth = 0;
+    let current = "";
+    for (const char of inner) {
+        if (char === "[" || char === "{" || char === "(")
+            depth++;
+        if (char === "]" || char === "}" || char === ")")
+            depth--;
+        if (char === "," && depth === 0) {
+            entries.push(current);
+            current = "";
+        }
+        else
+            current += char;
+    }
+    entries.push(current);
+    const kept = entries.map((entry) => entry.trim()).filter((entry) => entry && !new RegExp(`^${key}\\s*:`).test(entry));
+    const next = value === undefined ? kept : key === "mode" ? [`${key}: ${value}`, ...kept] : [...kept, `${key}: ${value}`];
+    const text = next.length ? `{ ${next.join(", ")} }` : "";
+    return source.slice(0, start) + text + source.slice(end);
+}

package/utils/workspace.d.ts

@@ -0,0 +1,13 @@
+import { type Tree } from "@nx/devkit";
+/** Whether new projects get inferred targets (official plugins' rule: `NX_ADD_PLUGINS` and nx.json `useInferencePlugins`). */
+export declare function shouldAddPlugin(tree: Tree, addPlugin: boolean | undefined): boolean;
+/** Appends missing lines to a `.gitignore`-style file. */
+export declare function ensureLines(tree: Tree, path: string, lines: string[]): void;
+/** The package manager workspaces globs (npm / yarn / bun `workspaces`, pnpm-workspace.yaml `packages`). */
+export declare function workspaceGlobs(tree: Tree): string[] | undefined;
+/** Whether `root` is a package manager workspace (its package.json dependencies get installed by the root install). */
+export declare function isWorkspacePackage(tree: Tree, root: string): boolean;
+/** Adds `root` to npm / yarn / bun `workspaces` when the root package.json has a workspaces list that misses it. */
+export declare function addToWorkspaces(tree: Tree, root: string): void;
+/** `../..` from a project root to the workspace root. */
+export declare function offsetTo(root: string): string;

package/utils/workspace.js

@@ -0,0 +1,63 @@
+// Workspace-level helpers shared by the generators.
+import { readJson, readNxJson, updateJson } from "@nx/devkit";
+/** Whether new projects get inferred targets (official plugins' rule: `NX_ADD_PLUGINS` and nx.json `useInferencePlugins`). */
+export function shouldAddPlugin(tree, addPlugin) {
+    if (addPlugin !== undefined)
+        return addPlugin;
+    if (process.env["NX_ADD_PLUGINS"] === "false")
+        return false;
+    return readNxJson(tree)?.useInferencePlugins !== false;
+}
+/** Appends missing lines to a `.gitignore`-style file. */
+export function ensureLines(tree, path, lines) {
+    const text = tree.exists(path) ? tree.read(path, "utf8") : "";
+    const have = new Set(text.split("\n").map((line) => line.trim()));
+    const missing = lines.filter((line) => !have.has(line));
+    if (!missing.length)
+        return;
+    tree.write(path, (text && !text.endsWith("\n") ? text + "\n" : text) + missing.join("\n") + "\n");
+}
+/** A workspaces glob (`apps/*`, `libs/**`) as a RegExp over project roots. */
+function globRegExp(pattern) {
+    const body = pattern
+        .replace(/\/+$/, "")
+        .split("/")
+        .map((part) => (part === "**" ? ".*" : part.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*")))
+        .join("/");
+    return new RegExp(`^${body}$`);
+}
+/** The package manager workspaces globs (npm / yarn / bun `workspaces`, pnpm-workspace.yaml `packages`). */
+export function workspaceGlobs(tree) {
+    if (tree.exists("pnpm-workspace.yaml")) {
+        const text = tree.read("pnpm-workspace.yaml", "utf8");
+        return [...text.matchAll(/^\s*-\s*["']?([^"'\n]+)["']?\s*$/gm)].map((match) => match[1].trim());
+    }
+    if (!tree.exists("package.json"))
+        return undefined;
+    const workspaces = readJson(tree, "package.json").workspaces;
+    if (!workspaces)
+        return undefined;
+    return Array.isArray(workspaces) ? workspaces : (workspaces.packages ?? []);
+}
+/** Whether `root` is a package manager workspace (its package.json dependencies get installed by the root install). */
+export function isWorkspacePackage(tree, root) {
+    const globs = workspaceGlobs(tree);
+    return Boolean(globs?.some((glob) => !glob.startsWith("!") && globRegExp(glob).test(root)));
+}
+/** Adds `root` to npm / yarn / bun `workspaces` when the root package.json has a workspaces list that misses it. */
+export function addToWorkspaces(tree, root) {
+    if (tree.exists("pnpm-workspace.yaml") || !tree.exists("package.json") || isWorkspacePackage(tree, root))
+        return;
+    updateJson(tree, "package.json", (pkg) => {
+        if (Array.isArray(pkg.workspaces))
+            pkg.workspaces.push(root);
+        else if (pkg.workspaces)
+            (pkg.workspaces.packages ??= []).push(root);
+        return pkg;
+    });
+}
+/** `../..` from a project root to the workspace root. */
+export function offsetTo(root) {
+    const depth = root.split("/").filter((part) => part && part !== ".").length;
+    return depth ? Array.from({ length: depth }, () => "..").join("/") : ".";
+}