@workit-dev/core 0.0.1 → 1.0.0

package/src/core/route-intent.ts

@@ -0,0 +1,305 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import {
+  expandGitAliases,
+  inWorkitWorkspace,
+  pushAction,
+  rawInvocations,
+  type RawInvocation,
+} from "../hooks/raw-git";
+import type { ShellDialect } from "../hooks/shell-words";
+import { validateBranchNameFor, type BranchNamePolicyCheck } from "./branch";
+
+/** A name a shell cannot settle before running (`$X`, `` `cmd` ``): never judged. */
+const UNKNOWABLE = /[$`*?[\]{}~]/u;
+
+const SWITCH_CREATE = new Set(["-c", "--create", "-C", "--force-create", "--orphan"]);
+const CHECKOUT_CREATE = new Set(["-b", "-B", "--orphan"]);
+const WORKTREE_CREATE = new Set(["-b", "-B"]);
+const SUBTREE_CREATE = new Set(["-b", "--branch"]);
+/** `git branch` options that list, delete or configure: no branch is created. */
+const BRANCH_NO_CREATE = new Set(
+  ["-d", "-D", "--delete", "-l", "--list", "-a", "--all", "-r", "--remotes", "--show-current"]
+    .concat(["-v", "-vv", "--verbose", "--contains", "--no-contains", "--merged", "--no-merged"])
+    .concat(["--points-at", "--sort", "--format", "--column", "--no-column", "-u"])
+    .concat(["--set-upstream-to", "--unset-upstream", "--edit-description", "-i", "--ignore-case"]),
+);
+/** `git branch -m|-c [<old>] <new>`: a rename or copy creates `<new>`. */
+const BRANCH_RENAME = new Set(["-m", "-M", "--move", "-c", "-C", "--copy"]);
+
+/** `--name` matches a long option in `flags`, whole or by git's unambiguous-prefix rule (`--cre`). */
+const longOption = (name: string, flags: ReadonlySet<string>): boolean =>
+  flags.has(name) ||
+  (name.length >= 3 && [...flags].some((flag) => flag.startsWith("--") && flag.startsWith(name)));
+
+/** The short options of `flags` (`-c` → `c`). */
+const shortsOf = (flags: ReadonlySet<string>): string =>
+  [...flags]
+    .filter((flag) => /^-[^-]$/u.test(flag))
+    .join("")
+    .replaceAll("-", "");
+
+/**
+ * The value of `flag` in `args`: `-c x`, `-cx`, a short cluster (`-fc x`),
+ * `--create=x`, `--create x` or an abbreviation (`--cre x`). Null when absent.
+ */
+const flagValue = (args: readonly string[], flags: ReadonlySet<string>): string | null => {
+  const shorts = shortsOf(flags);
+  for (let index = 1; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === "--") return null;
+    if (arg.startsWith("--")) {
+      const eq = arg.indexOf("=");
+      if (!longOption(eq > 0 ? arg.slice(0, eq) : arg, flags)) continue;
+      return eq > 0 ? arg.slice(eq + 1) : (args[index + 1] ?? null);
+    }
+    if (!arg.startsWith("-") || arg.length < 2) continue;
+    // A cluster of short switches; the creating one takes the rest or the next word.
+    for (let at = 1; at < arg.length; at++)
+      if (shorts.includes(arg[at]))
+        return at + 1 < arg.length ? arg.slice(at + 1) : (args[index + 1] ?? null);
+  }
+  return null;
+};
+
+/** `git worktree add` options that take a value. */
+const WORKTREE_VALUES = new Set(["--reason"]);
+
+/**
+ * `git worktree add [-b|-B <b>] <path> [<commit-ish>]`: the -b name, or, with
+ * only a path (no -b, -B, --detach or commit-ish), the branch git names after
+ * the path's last component.
+ */
+const worktreeTarget = (args: readonly string[]): string | null => {
+  const named = flagValue(args, WORKTREE_CREATE);
+  if (named !== null) return named;
+  const positionals: string[] = [];
+  for (let index = 1; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === "--detach" || arg === "-d") return null;
+    if (WORKTREE_VALUES.has(arg)) index++;
+    else if (!arg.startsWith("-")) positionals.push(arg);
+  }
+  if (positionals.length !== 1) return null;
+  const base = positionals[0].split(/[\\/]/u).findLast(Boolean) ?? "";
+  return base && base !== "." && base !== ".." ? base : null;
+};
+
+/** The branch `git branch …` creates (plain, rename or copy), or null. */
+const branchCommandTarget = (args: readonly string[]): string | null => {
+  let rename = false;
+  const positionals: string[] = [];
+  for (let index = 1; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === "--") {
+      positionals.push(...args.slice(index + 1));
+      break;
+    }
+    if (arg.startsWith("--")) {
+      const flag = arg.split("=", 1)[0];
+      if (longOption(flag, BRANCH_NO_CREATE)) return null;
+      if (longOption(flag, BRANCH_RENAME)) rename = true;
+    } else if (arg.startsWith("-") && arg.length > 1) {
+      // A short cluster: `-fm`, `-vv`, `-dr`.
+      const shorts = arg.slice(1).split("");
+      if (shorts.some((short) => BRANCH_NO_CREATE.has(`-${short}`))) return null;
+      if (shorts.some((short) => BRANCH_RENAME.has(`-${short}`))) rename = true;
+    } else positionals.push(arg);
+  }
+  if (positionals.length < 1 || positionals.length > 2) return null;
+  return rename ? (positionals.at(-1) ?? null) : positionals[0];
+};
+
+/** Positional words after `skip` leading words, past options; `values` take the next word. */
+const positionalsOf = (
+  args: readonly string[],
+  skip: number,
+  values: ReadonlySet<string> = new Set(),
+): string[] => {
+  const found: string[] = [];
+  for (let index = skip; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === "--") return [...found, ...args.slice(index + 1)];
+    if (values.has(arg)) index++;
+    else if (!arg.startsWith("-") || arg === "-") found.push(arg);
+  }
+  return found;
+};
+
+const localHead = (ref: string): string | null =>
+  ref.startsWith("refs/heads/") ? ref.slice("refs/heads/".length) : null;
+
+/** `git update-ref refs/heads/<b> <sha>` and `--stdin` `create|update refs/heads/<b>` lines. */
+const updateRefTargets = (args: readonly string[], stdin: string | undefined): string[] => {
+  if (args.some((arg) => arg === "-d" || arg === "--delete")) return [];
+  if (args.includes("--stdin"))
+    return (stdin ?? "")
+      .split(/[\n\0]/u)
+      .map((line) => /^\s*(?:create|update)\s+(\S+)/u.exec(line)?.[1] ?? "")
+      .map(localHead)
+      .filter((name): name is string => name !== null);
+  const [ref] = positionalsOf(args, 1, new Set(["-m"]));
+  const name = ref ? localHead(ref) : null;
+  return name ? [name] : [];
+};
+
+/** `git symbolic-ref HEAD refs/heads/<b>`: the next commit creates `<b>`. */
+const symbolicRefTarget = (args: readonly string[]): string | null => {
+  if (args.some((arg) => arg === "-d" || arg === "--delete")) return null;
+  const [, ref] = positionalsOf(args, 1, new Set(["-m"]));
+  return ref ? localHead(ref) : null;
+};
+
+/** git fetch/pull options that take a value. */
+const FETCH_VALUES = new Set(
+  ["--depth", "--deepen", "--shallow-since", "--shallow-exclude", "--refmap", "-j", "--jobs"]
+    .concat(["--upload-pack", "-o", "--server-option", "--negotiation-tip", "--filter"])
+    .concat(["--recurse-submodules-default", "--submodule-prefix", "-s", "--strategy", "-X"])
+    .concat(["--strategy-option"]),
+);
+
+/**
+ * `git fetch|pull <remote> <src>:<dst>` writes the local branch `<dst>`
+ * (`refs/heads/<dst>` or a bare name); `--stdin` reads the refspecs. A
+ * glob destination mirrors names the remote already has.
+ */
+const fetchTargets = (args: readonly string[], stdin: string | undefined): string[] => {
+  if (args.includes("--all") || args.includes("--multiple")) return [];
+  const specs = args.includes("--stdin")
+    ? (stdin ?? "").split(/\s+/u).filter(Boolean)
+    : positionalsOf(args, 1, FETCH_VALUES).slice(1);
+  const names: string[] = [];
+  for (const raw of specs) {
+    const colon = raw.indexOf(":");
+    const destination = colon >= 0 ? raw.slice(colon + 1) : "";
+    if (!destination || destination.includes("*")) continue;
+    const name = destination.startsWith("refs/") ? localHead(destination) : destination;
+    if (name) names.push(name);
+  }
+  return names;
+};
+
+/** `git push . <src>:<dst>` writes the local branch `<dst>`. */
+const localPushTargets = (args: string[]): string[] => {
+  const action = pushAction(args);
+  if (action?.kind !== "push" || action.remote !== "." || action.deletes) return [];
+  return action.targets.filter((name): name is string => name !== null);
+};
+
+/**
+ * The branches one git invocation creates: `switch -c|-C|--create <b>`,
+ * `checkout -b|-B <b>`, `branch [-m|-c] <b> [start]`, `worktree add -b|-B
+ * <b>`, `stash branch <b>`, `update-ref refs/heads/<b>`, `symbolic-ref HEAD
+ * refs/heads/<b>`, `fetch|pull <remote> <src>:<b>`, `push . <src>:<b>` and
+ * `subtree split -b <b>`, wherever the option stands. `args` start at the
+ * subcommand (after git's global options). Names a shell settles only when
+ * it runs (`$X`) are left out.
+ */
+export const gitBranchCreations = (args: string[], stdin?: string): string[] => {
+  const [sub, second] = args;
+  const targets: Array<string | null> =
+    sub === "switch"
+      ? [flagValue(args, SWITCH_CREATE)]
+      : sub === "checkout"
+        ? [flagValue(args, CHECKOUT_CREATE)]
+        : sub === "branch"
+          ? [branchCommandTarget(args)]
+          : sub === "worktree" && second === "add"
+            ? [worktreeTarget(args.slice(1))]
+            : sub === "stash" && second === "branch"
+              ? positionalsOf(args, 2).slice(0, 1)
+              : sub === "update-ref"
+                ? updateRefTargets(args, stdin)
+                : sub === "symbolic-ref"
+                  ? [symbolicRefTarget(args)]
+                  : sub === "fetch" || sub === "pull"
+                    ? fetchTargets(args, stdin)
+                    : sub === "push"
+                      ? localPushTargets(args)
+                      : sub === "subtree" && second === "split"
+                        ? [flagValue(args.slice(1), SUBTREE_CREATE)]
+                        : [];
+  return targets.filter(
+    (target): target is string =>
+      target !== null && target !== "" && !target.startsWith("-") && !UNKNOWABLE.test(target),
+  );
+};
+
+export type ShellBranchTarget = {
+  branch: string;
+  /** The directory git runs in, relative to the hook's cwd; undefined when unknowable. */
+  dir: string | null | undefined;
+};
+
+const targetsOf = (invocations: readonly RawInvocation[]): ShellBranchTarget[] =>
+  invocations.flatMap((invocation) =>
+    invocation.tool === "git"
+      ? gitBranchCreations(invocation.args, invocation.stdin).map((branch) => ({
+          branch,
+          dir: invocation.dir,
+        }))
+      : [],
+  );
+
+/**
+ * Every branch a shell command creates, through the raw-git tokenizer: `&&`,
+ * `;` and `|` chains, `cd`/`pushd` and `git -C`, env prefixes and wrappers,
+ * quoted names, compound commands and nested scripts (git aliases need the
+ * repository: see shellBranchPolicyViolation).
+ */
+export const shellBranchTargets = (
+  command: string,
+  dialect: ShellDialect = "posix",
+): ShellBranchTarget[] => targetsOf(rawInvocations(command, dialect));
+
+/** The first branch a shell command creates, or null. */
+export const shellBranchTarget = (command: string): string | null =>
+  shellBranchTargets(command)[0]?.branch ?? null;
+
+/** The branch already exists in `dir`: resetting or checking it out is not a new name. */
+const localBranchExists = (dir: string, branch: string): boolean =>
+  spawnSync("git", ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], {
+    cwd: dir,
+    stdio: "ignore",
+    timeout: 5_000,
+  }).status === 0;
+
+/** The directory a command judged from `root` runs git in, or null when not this policy's business. */
+const judgedDir = (root: string, dir: string | null | undefined): string | null => {
+  if (dir === undefined) return null;
+  if (dir === null) return root;
+  const resolved = path.resolve(root, dir);
+  return existsSync(resolved) && inWorkitWorkspace(resolved) ? resolved : null;
+};
+
+/**
+ * The branch policy verdict for every new branch a shell command creates,
+ * each checked in the directory git runs in (a linked worktree resolves to
+ * its main checkout's workspace). A command that runs in the hook's cwd is
+ * judged there. One that changes directory is judged only when that
+ * directory is known, already exists and is in a Workit workspace: a scratch
+ * repository (`cd "$(mktemp -d)"`, `git init x && cd x`, a fresh clone) is
+ * not the cwd workspace's business. A git alias is resolved there first. A
+ * name that already exists locally is skipped (`git branch -f legacy HEAD`).
+ * Null when no new branch is judged; the first violation otherwise.
+ */
+export const shellBranchPolicyViolation = (
+  root: string,
+  command: string,
+  dialect: ShellDialect = "posix",
+): BranchNamePolicyCheck | null => {
+  let judged = false;
+  const cache = new Map();
+  for (const raw of rawInvocations(command, dialect)) {
+    if (raw.tool !== "git" || judgedDir(root, raw.dir) === null) continue;
+    for (const target of targetsOf(expandGitAliases(root, raw, cache))) {
+      const dir = judgedDir(root, target.dir);
+      if (dir === null || localBranchExists(dir, target.branch)) continue;
+      judged = true;
+      const check = validateBranchNameFor(dir, target.branch);
+      if (!check.ok) return check;
+    }
+  }
+  return judged ? { ok: true } : null;
+};

package/src/core/rules.ts

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { configDir } from "./config";
+
+export type RulePlatform = "cursor" | "opencode";
+export type CanonicalRule = {
+  name: string;
+  description: string;
+  platforms: RulePlatform[];
+  body: string;
+};
+
+export const rulesDir = () => path.join(configDir(), "rules");
+
+export const parseRule = (markdown: string): CanonicalRule | { error: string } => {
+  const fm = markdown.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!fm)
+    return { error: "rule must start with frontmatter (--- name/description/platforms ---)" };
+  const meta: Record<string, string> = {};
+  const unquote = (v: string) => v.replace(/^["']|["']$/g, "").trim();
+  for (const line of fm[1].split("\n")) {
+    const idx = line.indexOf(":");
+    if (idx > 0) meta[line.slice(0, idx).trim()] = unquote(line.slice(idx + 1).trim());
+  }
+  const name = meta.name ?? "";
+  const description = meta.description ?? "";
+  const rawPlatforms = (meta.platforms ?? "")
+    .replace(/^\[|\]$/g, "")
+    .split(",")
+    .map((p) => p.trim().replace(/['"]/g, ""))
+    .filter(Boolean);
+  const platforms = rawPlatforms.filter(
+    (p): p is RulePlatform => p === "cursor" || p === "opencode",
+  );
+  if (!name || !description || platforms.length === 0) {
+    return { error: "rule frontmatter requires name, description, and platforms" };
+  }
+  if (platforms.length !== rawPlatforms.length) {
+    return { error: `invalid platform in frontmatter: ${rawPlatforms.join(", ")}` };
+  }
+  return { name, description, platforms, body: fm[2].trim() + "\n" };
+};
+
+const RULE_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+export const compileRuleCursor = (rule: CanonicalRule): string =>
+  `---\ndescription: ${rule.description}\nalwaysApply: true\n---\n\n${rule.body}`;
+
+export const writeCompiledCursorRules = (targetDir: string): string[] => {
+  const written: string[] = [];
+  const dir = rulesDir();
+  if (existsSync(dir)) {
+    for (const entry of readdirSync(dir)) {
+      const file = path.join(dir, entry, "rule.md");
+      if (!existsSync(file)) continue;
+      const parsed = parseRule(readFileSync(file, "utf8"));
+      if ("error" in parsed || !parsed.platforms.includes("cursor")) continue;
+      if (!RULE_NAME_RE.test(parsed.name)) continue;
+      const out = path.join(targetDir, `${parsed.name}.mdc`);
+      writeFileSync(out, compileRuleCursor(parsed), "utf8");
+      written.push(out);
+    }
+  }
+  return written;
+};

package/src/core/runtime-identity.ts

@@ -0,0 +1,63 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+/** sha256 of the exact bytes, lowercase hex. */
+export const sha256Hex = (bytes: string | Uint8Array): string =>
+  createHash("sha256").update(bytes).digest("hex");
+
+/** sha256 of a bundle file's bytes, or null when it cannot be read. */
+export const bundleHashOfFile = (file: string): string | null => {
+  try {
+    return sha256Hex(readFileSync(file));
+  } catch {
+    return null;
+  }
+};
+
+// Package-manager ephemeral caches, anchored to each one's layout so a `_npx`
+// or `dlx` directory anywhere else is never taken for one: npx's
+// `<npm cache>/_npx/<hash>/` (the cache is ~/.npm, %LocalAppData%\npm-cache or
+// $npm_config_cache), pnpm's `<pnpm cache>/dlx/<key>/` (~/.cache/pnpm,
+// ~/Library/Caches/pnpm, %LocalAppData%\pnpm-cache or $XDG_CACHE_HOME/pnpm)
+// and pacquet's ~/.pacquet. Installs resolving through these break when the
+// cache is cleared; one table here replaces the per-callsite substring lists.
+const EPHEMERAL_CACHE_LAYOUTS = [
+  /(?:^|\/)(?:\.npm|npm-cache)\/_npx\/[0-9a-f]+\//,
+  /(?:^|\/)(?:\.cache|caches)\/pnpm\/dlx\/[^/]+\//,
+  /(?:^|\/)pnpm-cache\/dlx\/[^/]+\//,
+  /(?:^|\/)\.pacquet\//,
+];
+
+const normalize = (entry: string): string => entry.replaceAll("\\", "/").toLowerCase();
+
+/** True when `normalized` holds `<dir>/<child>/<key>/` for a cache dir the env configures. */
+const underConfigured = (
+  normalized: string,
+  dir: string | undefined,
+  child: string,
+  key: RegExp,
+) => {
+  if (!dir) return false;
+  const prefix = `${normalize(dir).replace(/\/+$/, "")}/${child}/`;
+  const at = normalized.indexOf(prefix);
+  return at >= 0 && key.test(normalized.slice(at + prefix.length));
+};
+
+/** True when the entry resolves through a package-manager ephemeral cache. */
+export const isEphemeralCachePath = (
+  entry: string,
+  env: NodeJS.ProcessEnv = process.env,
+): boolean => {
+  if (!entry) return false;
+  const normalized = normalize(entry);
+  return (
+    EPHEMERAL_CACHE_LAYOUTS.some((layout) => layout.test(normalized)) ||
+    underConfigured(normalized, env.npm_config_cache, "_npx", /^[0-9a-f]+\//) ||
+    underConfigured(
+      normalized,
+      env.XDG_CACHE_HOME && `${env.XDG_CACHE_HOME}/pnpm`,
+      "dlx",
+      /^[^/]+\//,
+    )
+  );
+};

package/src/core/safe-write.ts

@@ -0,0 +1,87 @@
+import { randomUUID } from "node:crypto";
+import {
+  closeSync,
+  fchmodSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+
+// Shared credential-safe write (Task 14 Step 7 / CA-13): `wx` exclusive create
+// closes the TOCTOU window between an existence check and the write, and EEXIST
+// means the other writer won — their bytes are preserved instead of clobbered.
+// Every token write in the wizard (ensureToken), the apply path (create-file
+// mutations) and initApplyData routes through this one primitive.
+export type ExclusiveWriteResult = "created" | "preserved";
+
+export function writeFileExclusive(
+  file: string,
+  content: string,
+  mode?: number,
+): ExclusiveWriteResult {
+  try {
+    writeFileSync(file, content, { encoding: "utf8", flag: "wx", mode });
+    return "created";
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "EEXIST") return "preserved";
+    throw err;
+  }
+}
+
+export function writeFileAtomic(file: string, content: string, mode?: number): void {
+  const absolute = path.resolve(file);
+  let parent = path.dirname(absolute);
+  const root = path.parse(parent).root;
+  for (;;) {
+    try {
+      if (lstatSync(parent).isSymbolicLink()) throw new Error(`symlinked write path: ${parent}`);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+    const next = path.dirname(parent);
+    if (parent === root || next === parent) break;
+    parent = next;
+  }
+
+  const directory = path.dirname(absolute);
+  mkdirSync(directory, { recursive: true });
+  let existing: ReturnType<typeof lstatSync> | null = null;
+  try {
+    existing = lstatSync(absolute);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  if (existing?.isSymbolicLink() || (existing && !existing.isFile())) {
+    throw new Error(`refusing to replace non-regular file: ${absolute}`);
+  }
+  const temporary = `${absolute}.${randomUUID()}.tmp`;
+  let fd: number | undefined;
+  try {
+    fd = openSync(temporary, "wx", mode ?? 0o666);
+    writeFileSync(fd, content, "utf8");
+    if (existing) fchmodSync(fd, existing.mode & 0o777);
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = undefined;
+    renameSync(temporary, absolute);
+  } catch (error) {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        // Keep the original write error.
+      }
+    }
+    try {
+      unlinkSync(temporary);
+    } catch {
+      // The temporary may already have been renamed or removed.
+    }
+    throw error;
+  }
+}

package/src/core/scope-glob.ts

@@ -0,0 +1,56 @@
+// Scope path containment with globs (#647). A scope path covers itself and
+// everything under what it matches: `docs` covers `docs/x`, `packages/**`
+// covers `packages/x/src/**`, `apps/*` covers `apps/web/app/**`. An inner
+// glob counts as contained only when every path it can match is: `**` or a
+// wildcard segment on the inside is matched by `**` or the same segment on
+// the outside, never by a narrower pattern.
+
+const GLOB = /[*?[\]{}]/u;
+
+const segmentRegex = (pattern: string): RegExp => {
+  let out = "";
+  let braces = 0;
+  for (const char of pattern) {
+    if (char === "*") out += "[^/]*";
+    else if (char === "?") out += "[^/]";
+    else if (char === "{") {
+      braces += 1;
+      out += "(?:";
+    } else if (char === "}" && braces > 0) {
+      braces -= 1;
+      out += ")";
+    } else if (char === "," && braces > 0) out += "|";
+    else out += char.replace(/[.+^$()|\\[\]{}]/u, "\\$&");
+  }
+  // An unclosed brace is a literal character elsewhere; here it never matches.
+  if (braces > 0) return /$^/u;
+  return new RegExp(`^${out}$`, "u");
+};
+
+const segmentCovers = (outer: string, inner: string): boolean => {
+  if (outer === inner) return true;
+  // A wildcard inside is wider than any outer pattern other than itself.
+  if (GLOB.test(inner) || !GLOB.test(outer)) return false;
+  return segmentRegex(outer).test(inner);
+};
+
+const prefixCovers = (outer: readonly string[], inner: readonly string[]): boolean => {
+  if (outer.length === 0) return true;
+  if (outer[0] === "**") {
+    for (let skip = 0; skip <= inner.length; skip += 1)
+      if (prefixCovers(outer.slice(1), inner.slice(skip))) return true;
+    return false;
+  }
+  if (inner.length === 0) return false;
+  return segmentCovers(outer[0], inner[0]) && prefixCovers(outer.slice(1), inner.slice(1));
+};
+
+/** Whether scope path `outer` (a path or glob) covers `inner` and everything under it. */
+export function scopePathCovers(outer: string, inner: string): boolean {
+  // `..` climbs out of whatever the outer path names; it is never inside it.
+  if (inner.split("/").includes("..")) return outer === inner;
+  if (outer === "." || outer === inner || inner.startsWith(`${outer}/`)) return true;
+  if (!GLOB.test(outer)) return false;
+  const split = (value: string) => value.split("/").filter((part) => part !== "" && part !== ".");
+  return prefixCovers(split(outer), split(inner));
+}

package/src/core/scripts.ts

@@ -0,0 +1,6 @@
+import { assetRoot, packageRoot } from "./package-root";
+
+export const PLUGIN_ROOT = packageRoot();
+export const ASSET_ROOT = assetRoot();
+
+export const resolveWorkspaceRoot = (explicit?: string) => explicit || process.cwd();