@howells/boundaries 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# @howells/boundaries
+
+Opinionated package-boundary conventions for Turborepo workspaces.
+
+The executable is `boundaries`.
+
+## Install
+
+```sh
+pnpm add -D @howells/boundaries
+```
+
+## Use
+
+Initialize boundary config:
+
+```sh
+pnpm exec boundaries init
+```
+
+This adds:
+
+- root `turbo.json` boundary rules
+- package-level `turbo.json` tags
+- a root `package.json` script: `"boundaries": "boundaries check"`
+
+Run checks:
+
+```sh
+pnpm boundaries
+```
+
+or:
+
+```sh
+pnpm exec boundaries check
+```
+
+Explain a relationship:
+
+```sh
+pnpm exec boundaries explain apps/web packages/ui
+pnpm exec boundaries explain apps/web apps/admin
+```
+
+## Default Policy
+
+The default tags are:
+
+```text
+type:app
+type:package
+type:tooling
+scope:<workspace-name>
+visibility:public
+visibility:internal
+```
+
+The default rules are:
+
+```text
+type:app      cannot depend on type:app
+type:package  cannot depend on type:app
+type:tooling  cannot depend on type:app
+```
+
+This blocks app-to-app imports and keeps shared packages from reaching into deployable apps.
+
+`visibility:*` tags are generated as metadata, but no default rule is attached to them yet. Public packages often depend on private dev tooling packages, so runtime visibility policy needs a more precise model.
+
+## Backend
+
+`boundaries check` validates the generated convention layer, then delegates to:
+
+```sh
+turbo boundaries
+```
+
+Use this in Turborepo repos that already have `turbo` installed.

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@howells/boundaries",
+  "version": "0.1.0",
+  "description": "Opinionated Turborepo package boundary conventions.",
+  "type": "module",
+  "bin": {
+    "boundaries": "./src/cli.js"
+  },
+  "license": "MIT",
+  "files": [
+    "README.md",
+    "src",
+    "skills"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/skills/howells-boundaries/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: howells-boundaries
+description: Use when adding, checking, explaining, or repairing package-level architecture boundaries in Turborepo JavaScript/TypeScript monorepos with the `boundaries` CLI from `@howells/boundaries`.
+---
+
+# Howells Boundaries
+
+Use `@howells/boundaries` for package-level architecture enforcement in Turborepo workspaces. The executable is `boundaries`.
+
+## Workflow
+
+1. Confirm the repo is a Turborepo workspace by checking for `turbo.json` and workspace packages in `package.json`, `pnpm-workspace.yaml`, or equivalent package-manager config.
+2. Install or use `@howells/boundaries` from the repo’s chosen package manager.
+3. Run `boundaries init` to add root Turbo boundary rules and per-package `turbo.json` tags.
+4. Review generated tags before accepting them. Fix incorrect tags instead of weakening policy.
+5. Run `boundaries check`.
+6. If a violation appears, prefer fixing the import or dependency declaration. Use exceptions only when they are narrow, temporary, and documented.
+
+## Default Model
+
+Use these package tags unless the repo already has a clearer convention:
+
+```text
+type:app
+type:package
+type:tooling
+scope:<name>
+platform:browser
+platform:node
+visibility:public
+visibility:internal
+```
+
+Default rules:
+
+```text
+type:app      cannot depend on type:app
+type:package  cannot depend on type:app
+type:tooling  cannot depend on type:app
+```
+
+This blocks app-to-app imports and keeps shared packages from reaching into deployable apps. Treat `visibility:*` as metadata until the checker can distinguish runtime dependencies from dev-only tooling dependencies.
+
+## Good Fixes
+
+- Move shared code from an app into a package, then import the package.
+- Add a missing internal package dependency to the importing package’s `package.json`.
+- Use the package public entrypoint instead of importing files across package directories.
+- Split package tags by purpose when a package has unclear ownership.
+
+## Avoid
+
+- Do not use ESLint as the primary enforcement mechanism.
+- Do not add broad allowlists to make a check pass.
+- Do not move task logic into root `package.json`; keep Turbo package tasks in packages and root scripts as delegators.
+- Do not invent package-internal layer rules for this tool. Keep v1 package-level; use another tool later for module-level boundaries if needed.
+
+## Fallbacks
+
+Use `turbo boundaries` as the backend when available. Consider `dependency-cruiser` or `rev-dep` only when the user asks for graph analysis that Turbo boundaries cannot answer.

package/skills/howells-boundaries/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Howells Boundaries"
+  short_description: "Turborepo package boundary enforcement"
+  default_prompt: "Use $howells-boundaries to add and check package-level boundaries in this Turborepo workspace."
+
+policy:
+  allow_implicit_invocation: true

package/src/check.js

@@ -0,0 +1,85 @@
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { discoverWorkspaces } from "./init.js";
+
+export async function checkRepository({
+  root = process.cwd(),
+  runTurbo = true,
+  stdout = process.stdout,
+  stderr = process.stderr,
+} = {}) {
+  const rootPackageJson = await readJson(join(root, "package.json"));
+  const rootTurboJson = await readJson(join(root, "turbo.json"), {});
+  const workspaces = await discoverWorkspaces(root, rootPackageJson);
+  const errors = await validateBoundarySetup(root, rootTurboJson, workspaces);
+
+  if (errors.length > 0) {
+    for (const error of errors) {
+      stderr.write(`boundaries: ${error}\n`);
+    }
+    return { ok: false, exitCode: 1, errors };
+  }
+
+  if (!runTurbo) {
+    stdout.write(`Boundary configuration is valid for ${workspaces.length} workspace${workspaces.length === 1 ? "" : "s"}.\n`);
+    return { ok: true, exitCode: 0, errors: [] };
+  }
+
+  const turboExitCode = await runTurboBoundaries({ root });
+  return {
+    ok: turboExitCode === 0,
+    exitCode: turboExitCode,
+    errors: [],
+  };
+}
+
+async function validateBoundarySetup(root, rootTurboJson, workspaces) {
+  const errors = [];
+
+  if (!rootTurboJson.boundaries?.tags) {
+    errors.push("root turbo.json is missing boundaries.tags; run `boundaries init`.");
+  }
+
+  for (const workspace of workspaces) {
+    const packageTurboJson = await readJson(join(root, workspace.path, "turbo.json"), {});
+    if (!Array.isArray(packageTurboJson.tags) || packageTurboJson.tags.length === 0) {
+      errors.push(`${workspace.path}/turbo.json is missing package boundary tags.`);
+    }
+  }
+
+  return errors;
+}
+
+function runTurboBoundaries({ root }) {
+  return new Promise((resolve) => {
+    const child = spawn("turbo", ["boundaries"], {
+      cwd: root,
+      shell: process.platform === "win32",
+      stdio: "inherit",
+    });
+
+    child.on("error", (error) => {
+      process.stderr.write(
+        `boundaries: could not run \`turbo boundaries\` (${error.message}). Install turbo or run \`boundaries check --no-turbo\`.\n`,
+      );
+      resolve(1);
+    });
+
+    child.on("close", (code) => {
+      resolve(code ?? 1);
+    });
+  });
+}
+
+async function readJson(filePath, fallback = undefined) {
+  try {
+    return JSON.parse(await readFile(filePath, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT" && fallback !== undefined) {
+      return fallback;
+    }
+    throw error;
+  }
+}

package/src/cli.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { checkRepository } from "./check.js";
+import { evaluateDependency } from "./core.js";
+import { discoverWorkspaces, initRepository } from "./init.js";
+
+const HELP = `Usage: boundaries <command>
+
+Commands:
+  init                 Add Howells boundary conventions to a Turborepo workspace
+  check [--no-turbo]   Validate boundary config and run turbo boundaries
+  explain <from> <to>  Explain whether one workspace may depend on another
+  help                 Show this help
+`;
+
+async function main(argv) {
+  const [command, ...args] = argv;
+
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    process.stdout.write(HELP);
+    return 0;
+  }
+
+  if (command === "init") {
+    const result = await initRepository();
+    process.stdout.write(
+      `Initialized boundaries for ${result.workspaces.length} workspace${result.workspaces.length === 1 ? "" : "s"}.\n`,
+    );
+    return 0;
+  }
+
+  if (command === "check") {
+    const result = await checkRepository({
+      runTurbo: !args.includes("--no-turbo"),
+    });
+    return result.exitCode;
+  }
+
+  if (command === "explain") {
+    return explain(args);
+  }
+
+  process.stderr.write(`Unknown command: ${command}\n\n${HELP}`);
+  return 1;
+}
+
+async function explain(args) {
+  const [fromSelector, toSelector] = args;
+  if (!fromSelector || !toSelector) {
+    process.stderr.write("Usage: boundaries explain <from> <to>\n");
+    return 1;
+  }
+
+  const root = process.cwd();
+  const rootPackageJson = await readJson(join(root, "package.json"));
+  const rootTurboJson = await readJson(join(root, "turbo.json"));
+  const workspaces = await discoverWorkspaces(root, rootPackageJson);
+  const from = findWorkspace(workspaces, fromSelector);
+  const to = findWorkspace(workspaces, toSelector);
+
+  if (!from || !to) {
+    process.stderr.write("Could not find both workspaces. Use a package name or workspace path.\n");
+    return 1;
+  }
+
+  const decision = evaluateDependency({
+    rootConfig: rootTurboJson,
+    fromName: from.name,
+    fromTags: await readTags(root, from),
+    toName: to.name,
+    toTags: await readTags(root, to),
+  });
+
+  process.stdout.write(
+    `${from.name ?? from.path} -> ${to.name ?? to.path}: ${decision.allowed ? "allowed" : "blocked"}\n${decision.reason}\n`,
+  );
+
+  return decision.allowed ? 0 : 1;
+}
+
+function findWorkspace(workspaces, selector) {
+  return workspaces.find((workspace) => {
+    return workspace.name === selector || workspace.path === selector || workspace.path.endsWith(`/${selector}`);
+  });
+}
+
+async function readTags(root, workspace) {
+  const turboJson = await readJson(join(root, workspace.path, "turbo.json"), {});
+  return turboJson.tags ?? [];
+}
+
+async function readJson(filePath, fallback = undefined) {
+  try {
+    return JSON.parse(await readFile(filePath, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT" && fallback !== undefined) {
+      return fallback;
+    }
+    throw error;
+  }
+}
+
+main(process.argv.slice(2))
+  .then((exitCode) => {
+    process.exitCode = exitCode;
+  })
+  .catch((error) => {
+    process.stderr.write(`boundaries: ${error.message}\n`);
+    process.exitCode = 1;
+  });

package/src/core.js

@@ -0,0 +1,235 @@
+const DEFAULT_ROOT_BOUNDARY_TAGS = {
+  "type:app": {
+    dependencies: {
+      deny: ["type:app"],
+    },
+  },
+  "type:package": {
+    dependencies: {
+      deny: ["type:app"],
+    },
+  },
+  "type:tooling": {
+    dependencies: {
+      deny: ["type:app"],
+    },
+  },
+};
+
+export function inferTagsForWorkspace(workspace) {
+  const normalizedPath = normalizePath(workspace.path);
+  const packageName = workspace.name ?? "";
+  const scope = inferScope(normalizedPath, packageName);
+  const type = inferType(normalizedPath);
+  const visibility = workspace.packageJson?.private === false ? "public" : "internal";
+
+  return [`type:${type}`, `scope:${scope}`, `visibility:${visibility}`];
+}
+
+export function createPackageTurboConfig(currentConfig = {}, tags) {
+  return {
+    ...currentConfig,
+    extends: ensureRootExtends(currentConfig.extends),
+    tags: unique(tags),
+  };
+}
+
+export function applyRootBoundaryConfig(currentConfig = {}) {
+  return {
+    ...currentConfig,
+    boundaries: {
+      ...(currentConfig.boundaries ?? {}),
+      tags: mergeBoundaryTags(
+        DEFAULT_ROOT_BOUNDARY_TAGS,
+        currentConfig.boundaries?.tags ?? {},
+      ),
+    },
+  };
+}
+
+export function evaluateDependency({
+  rootConfig,
+  fromTags,
+  toTags,
+  fromName,
+  toName,
+}) {
+  const tagRules = rootConfig.boundaries?.tags ?? {};
+  const targetSelectors = new Set([...toTags, toName].filter(Boolean));
+  const sourceSelectors = new Set([...fromTags, fromName].filter(Boolean));
+
+  for (const fromTag of fromTags) {
+    const dependencyDecision = evaluateRuleSet({
+      ruleSet: tagRules[fromTag]?.dependencies,
+      candidateSelectors: targetSelectors,
+      direction: "dependency",
+      activeTag: fromTag,
+    });
+
+    if (!dependencyDecision.allowed) {
+      return dependencyDecision;
+    }
+  }
+
+  for (const toTag of toTags) {
+    const dependentDecision = evaluateRuleSet({
+      ruleSet: tagRules[toTag]?.dependents,
+      candidateSelectors: sourceSelectors,
+      direction: "dependent",
+      activeTag: toTag,
+    });
+
+    if (!dependentDecision.allowed) {
+      return dependentDecision;
+    }
+  }
+
+  return { allowed: true, reason: "No boundary rule blocks this dependency." };
+}
+
+function evaluateRuleSet({ ruleSet, candidateSelectors, direction, activeTag }) {
+  if (!ruleSet) {
+    return { allowed: true };
+  }
+
+  const denied = ruleSet.deny?.find((selector) => candidateSelectors.has(selector));
+  if (denied) {
+    return {
+      allowed: false,
+      reason: `${activeTag} denies ${direction} selector ${denied}.`,
+    };
+  }
+
+  if (ruleSet.allow?.length > 0) {
+    const allowed = ruleSet.allow.some((selector) => candidateSelectors.has(selector));
+    if (!allowed) {
+      return {
+        allowed: false,
+        reason: `${activeTag} only allows ${direction} selectors: ${ruleSet.allow.join(", ")}.`,
+      };
+    }
+  }
+
+  return { allowed: true };
+}
+
+function mergeBoundaryTags(defaultTags, existingTags) {
+  const merged = { ...defaultTags, ...existingTags };
+
+  for (const tag of Object.keys(defaultTags)) {
+    merged[tag] = mergeBoundaryTag(defaultTags[tag], existingTags[tag] ?? {});
+  }
+
+  return merged;
+}
+
+function mergeBoundaryTag(defaultTag, existingTag) {
+  const merged = {
+    ...defaultTag,
+    ...existingTag,
+    dependencies: mergeRelationship(
+      defaultTag.dependencies,
+      existingTag.dependencies,
+    ),
+    dependents: mergeRelationship(defaultTag.dependents, existingTag.dependents),
+  };
+
+  if (!merged.dependencies) {
+    delete merged.dependencies;
+  }
+
+  if (!merged.dependents) {
+    delete merged.dependents;
+  }
+
+  return merged;
+}
+
+function mergeRelationship(defaultRelationship, existingRelationship) {
+  if (!defaultRelationship && !existingRelationship) {
+    return undefined;
+  }
+
+  const merged = {
+    ...(defaultRelationship ?? {}),
+    ...(existingRelationship ?? {}),
+  };
+
+  const allow = unique([
+    ...(defaultRelationship?.allow ?? []),
+    ...(existingRelationship?.allow ?? []),
+  ]);
+  const deny = unique([
+    ...(defaultRelationship?.deny ?? []),
+    ...(existingRelationship?.deny ?? []),
+  ]);
+
+  if (allow.length > 0) {
+    merged.allow = allow;
+  } else {
+    delete merged.allow;
+  }
+
+  if (deny.length > 0) {
+    merged.deny = deny;
+  } else {
+    delete merged.deny;
+  }
+
+  return merged;
+}
+
+function inferType(workspacePath) {
+  if (workspacePath.startsWith("apps/") || workspacePath === "apps") {
+    return "app";
+  }
+
+  if (
+    workspacePath.startsWith("tooling/") ||
+    workspacePath.startsWith("tools/") ||
+    workspacePath.includes("/eslint") ||
+    workspacePath.includes("/lint") ||
+    workspacePath.includes("/config")
+  ) {
+    return "tooling";
+  }
+
+  return "package";
+}
+
+function inferScope(workspacePath, packageName) {
+  const pathParts = workspacePath.split("/").filter(Boolean);
+  if (pathParts.length > 1) {
+    return sanitizeTagValue(pathParts.at(-1));
+  }
+
+  const unscopedName = packageName.includes("/")
+    ? packageName.split("/").at(-1)
+    : packageName;
+
+  return sanitizeTagValue(unscopedName || pathParts.at(-1) || "unknown");
+}
+
+function ensureRootExtends(extendsValue) {
+  if (!Array.isArray(extendsValue) || extendsValue.length === 0) {
+    return ["//"];
+  }
+
+  if (extendsValue[0] === "//") {
+    return extendsValue;
+  }
+
+  return ["//", ...extendsValue.filter((value) => value !== "//")];
+}
+
+function normalizePath(value) {
+  return value.replaceAll("\\", "/").replace(/^\.?\//, "").replace(/\/$/, "");
+}
+
+function sanitizeTagValue(value) {
+  return value.toLowerCase().replace(/^@/, "").replaceAll(/[^a-z0-9._-]+/g, "-");
+}
+
+function unique(values) {
+  return [...new Set(values.filter((value) => value !== undefined))];
+}

package/src/init.js

@@ -0,0 +1,164 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import {
+  applyRootBoundaryConfig,
+  createPackageTurboConfig,
+  inferTagsForWorkspace,
+} from "./core.js";
+
+export async function initRepository({ root = process.cwd() } = {}) {
+  const rootPackageJsonPath = join(root, "package.json");
+  const rootTurboJsonPath = join(root, "turbo.json");
+  const rootPackageJson = await readJson(rootPackageJsonPath);
+  const rootTurboJson = await readJson(rootTurboJsonPath, {});
+  const workspaces = await discoverWorkspaces(root, rootPackageJson);
+
+  rootPackageJson.scripts = {
+    ...(rootPackageJson.scripts ?? {}),
+    boundaries: rootPackageJson.scripts?.boundaries ?? "boundaries check",
+  };
+
+  await writeJson(rootPackageJsonPath, rootPackageJson);
+  await writeJson(rootTurboJsonPath, applyRootBoundaryConfig(rootTurboJson));
+
+  for (const workspace of workspaces) {
+    const turboJsonPath = join(root, workspace.path, "turbo.json");
+    const currentTurboJson = await readJson(turboJsonPath, {});
+    const tags = inferTagsForWorkspace(workspace);
+    await writeJson(turboJsonPath, createPackageTurboConfig(currentTurboJson, tags));
+  }
+
+  return { workspaces };
+}
+
+export async function discoverWorkspaces(root, rootPackageJson = undefined) {
+  const packageJson = rootPackageJson ?? (await readJson(join(root, "package.json")));
+  const patterns = await workspacePatterns(root, packageJson);
+  const workspaces = [];
+
+  for (const pattern of patterns) {
+    workspaces.push(...(await discoverPattern(root, pattern)));
+  }
+
+  return workspaces
+    .sort((left, right) => left.path.localeCompare(right.path))
+    .filter((workspace, index, allWorkspaces) => {
+      return allWorkspaces.findIndex((candidate) => candidate.path === workspace.path) === index;
+    });
+}
+
+async function workspacePatterns(root, packageJson) {
+  if (Array.isArray(packageJson.workspaces)) {
+    return packageJson.workspaces;
+  }
+
+  if (Array.isArray(packageJson.workspaces?.packages)) {
+    return packageJson.workspaces.packages;
+  }
+
+  const pnpmWorkspace = await readText(join(root, "pnpm-workspace.yaml"), null);
+  if (pnpmWorkspace) {
+    const patterns = parsePnpmWorkspacePackages(pnpmWorkspace);
+    if (patterns.length > 0) {
+      return patterns;
+    }
+  }
+
+  return ["apps/*", "packages/*"];
+}
+
+function parsePnpmWorkspacePackages(contents) {
+  const patterns = [];
+  let inPackages = false;
+
+  for (const rawLine of contents.split("\n")) {
+    const line = rawLine.replace(/\s+#.*$/, "");
+    if (/^packages:\s*$/.test(line)) {
+      inPackages = true;
+      continue;
+    }
+
+    if (inPackages && /^\S/.test(line) && !line.startsWith("packages:")) {
+      inPackages = false;
+    }
+
+    if (!inPackages) {
+      continue;
+    }
+
+    const match = line.match(/^\s*-\s+["']?([^"']+)["']?\s*$/);
+    if (match && !match[1].startsWith("!")) {
+      patterns.push(match[1]);
+    }
+  }
+
+  return patterns;
+}
+
+async function discoverPattern(root, pattern) {
+  if (!pattern.endsWith("/*")) {
+    return [];
+  }
+
+  const parentPath = pattern.slice(0, -2);
+  const absoluteParentPath = join(root, parentPath);
+  let entries;
+
+  try {
+    entries = await readdir(absoluteParentPath, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+
+  const workspaces = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+
+    const workspacePath = `${parentPath}/${entry.name}`;
+    const packageJson = await readJson(join(root, workspacePath, "package.json"), null);
+    if (!packageJson) {
+      continue;
+    }
+
+    workspaces.push({
+      name: packageJson.name,
+      packageJson,
+      path: workspacePath,
+    });
+  }
+
+  return workspaces;
+}
+
+async function readJson(filePath, fallback = undefined) {
+  try {
+    return JSON.parse(await readFile(filePath, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT" && fallback !== undefined) {
+      return fallback;
+    }
+    throw error;
+  }
+}
+
+async function readText(filePath, fallback = undefined) {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT" && fallback !== undefined) {
+      return fallback;
+    }
+    throw error;
+  }
+}
+
+async function writeJson(filePath, value) {
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}