@howells/boundaries 0.1.0 → 0.1.2

package/AGENTS.md

@@ -0,0 +1,46 @@
+# @howells/boundaries
+
+Package-level boundary conventions for Turborepo workspaces. The npm package is `@howells/boundaries`; the executable is `boundaries`.
+
+## Commands
+
+```sh
+npm test                         # Run unit and CLI contract tests
+npm run validate:skill            # Validate bundled Codex skill metadata
+npm run smoke:install             # Pack, install in a temp project, run the bin
+npm pack --dry-run                # Inspect publish contents
+node src/cli.js --schema          # Print machine-readable command schema
+node src/cli.js init --dry-run    # Preview generated Turbo boundary files
+```
+
+## Key Files
+
+- `src/cli.js`: command parsing and output formatting.
+- `src/init.js`: workspace discovery and config generation.
+- `src/check.js`: local config validation and `turbo boundaries` delegation.
+- `src/core.js`: tag inference and dependency rule evaluation.
+- `src/schema.js`: machine-readable CLI schema.
+- `skills/howells-boundaries/SKILL.md`: bundled Codex skill.
+
+## Conventions
+
+- Keep the tool package-level. Do not add package-internal layer enforcement here.
+- Prefer Turbo `boundaries` as the backend; this package is a convention layer.
+- CLI commands must stay non-interactive.
+- Any new command output should support `--json` when an agent may consume it.
+- Mutating commands should support `--dry-run` before they write files.
+
+## Permissions
+
+Always:
+- Read and edit files in this package.
+- Run `npm test`, `npm run validate:skill`, and `npm pack --dry-run`.
+
+Ask first:
+- Publish a new npm version.
+- Change the default boundary policy.
+- Add runtime dependencies.
+
+Never:
+- Weaken generated boundary rules just to silence violations.
+- Edit user repos outside this package unless explicitly asked.

package/README.md

@@ -12,6 +12,13 @@ pnpm add -D @howells/boundaries
 
 ## Use
 
+Try without installing:
+
+```sh
+npx @howells/boundaries --help
+npx @howells/boundaries init --dry-run
+```
+
 Initialize boundary config:
 
 ```sh
@@ -43,6 +50,14 @@ pnpm exec boundaries explain apps/web packages/ui
 pnpm exec boundaries explain apps/web apps/admin
 ```
 
+Machine-readable output:
+
+```sh
+pnpm exec boundaries --schema
+pnpm exec boundaries init --dry-run --json
+pnpm exec boundaries explain apps/web packages/ui --json
+```
+
 ## Default Policy
 
 The default tags are:

package/package.json

@@ -1,19 +1,39 @@
 {
   "name": "@howells/boundaries",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Opinionated Turborepo package boundary conventions.",
   "type": "module",
   "bin": {
-    "boundaries": "./src/cli.js"
+    "boundaries": "src/cli.js"
   },
   "license": "MIT",
+  "keywords": [
+    "turborepo",
+    "monorepo",
+    "boundaries",
+    "architecture",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/howells/boundaries.git"
+  },
+  "bugs": {
+    "url": "https://github.com/howells/boundaries/issues"
+  },
+  "homepage": "https://www.npmjs.com/package/@howells/boundaries",
   "files": [
+    "AGENTS.md",
     "README.md",
+    "scripts",
     "src",
     "skills"
   ],
   "scripts": {
-    "test": "node --test"
+    "prepack": "npm test && npm run validate:skill",
+    "smoke:install": "node scripts/smoke-install.mjs",
+    "test": "node --test",
+    "validate:skill": "node scripts/validate-skill.mjs"
   },
   "engines": {
     "node": ">=20"

package/scripts/smoke-install.mjs

@@ -0,0 +1,32 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, unlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const root = new URL("..", import.meta.url);
+const temp = await mkdtemp(join(tmpdir(), "boundaries-smoke-"));
+
+const { stdout: packOutput } = await execFileAsync("npm", ["pack", "--pack-destination", temp], {
+  cwd: root,
+});
+const filename = packOutput
+  .split("\n")
+  .map((line) => line.trim())
+  .find((line) => line.endsWith(".tgz"));
+if (!filename) {
+  throw new Error(`Could not find packed tarball in npm pack output:\n${packOutput}`);
+}
+const tarball = join(temp, filename);
+
+await execFileAsync("npm", ["init", "-y"], { cwd: temp });
+await execFileAsync("npm", ["install", tarball, "--ignore-scripts"], { cwd: temp });
+
+const { stdout } = await execFileAsync("npx", ["boundaries", "--help"], { cwd: temp });
+if (!stdout.includes("Usage: boundaries <command>")) {
+  throw new Error("Installed boundaries binary did not print expected help.");
+}
+
+process.stdout.write(`Smoke install passed in ${temp}\n`);
+await unlink(tarball);

package/scripts/validate-skill.mjs

@@ -0,0 +1,31 @@
+import { readFile } from "node:fs/promises";
+
+const skillPath = new URL("../skills/howells-boundaries/SKILL.md", import.meta.url);
+const skill = await readFile(skillPath, "utf8");
+
+if (!skill.startsWith("---\n")) {
+  fail("SKILL.md must start with YAML frontmatter.");
+}
+
+const end = skill.indexOf("\n---\n", 4);
+if (end === -1) {
+  fail("SKILL.md frontmatter is not closed.");
+}
+
+const frontmatter = skill.slice(4, end);
+for (const field of ["name:", "description:"]) {
+  if (!frontmatter.includes(field)) {
+    fail(`SKILL.md frontmatter is missing ${field}`);
+  }
+}
+
+if (!skill.includes("boundaries init") || !skill.includes("boundaries check")) {
+  fail("SKILL.md must document init and check workflows.");
+}
+
+process.stdout.write("Skill is valid.\n");
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}

package/src/check.js

@@ -9,6 +9,7 @@ export async function checkRepository({
   runTurbo = true,
   stdout = process.stdout,
   stderr = process.stderr,
+  quiet = false,
 } = {}) {
   const rootPackageJson = await readJson(join(root, "package.json"));
   const rootTurboJson = await readJson(join(root, "turbo.json"), {});
@@ -16,22 +17,29 @@ export async function checkRepository({
   const errors = await validateBoundarySetup(root, rootTurboJson, workspaces);
 
   if (errors.length > 0) {
-    for (const error of errors) {
-      stderr.write(`boundaries: ${error}\n`);
+    if (!quiet) {
+      for (const error of errors) {
+        stderr.write(`boundaries: ${error.message}\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: [] };
+    if (!quiet) {
+      stdout.write(`Boundary configuration is valid for ${workspaces.length} workspace${workspaces.length === 1 ? "" : "s"}.\n`);
+    }
+    return { ok: true, exitCode: 0, errors: [], workspaces };
   }
 
-  const turboExitCode = await runTurboBoundaries({ root });
+  const turboResult = await runTurboBoundaries({ root, quiet });
+  const turboExitCode = turboResult.exitCode;
   return {
     ok: turboExitCode === 0,
     exitCode: turboExitCode,
-    errors: [],
+    errors: turboExitCode === 0 ? [] : [turboResult.error],
+    turbo: turboResult,
+    workspaces,
   };
 }
 
@@ -39,36 +47,78 @@ async function validateBoundarySetup(root, rootTurboJson, workspaces) {
   const errors = [];
 
   if (!rootTurboJson.boundaries?.tags) {
-    errors.push("root turbo.json is missing boundaries.tags; run `boundaries init`.");
+    errors.push({
+      code: "ROOT_BOUNDARIES_MISSING",
+      message: "root turbo.json is missing boundaries.tags; run `boundaries init`.",
+      file: "turbo.json",
+      is_retriable: false,
+      suggestions: ["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.`);
+      errors.push({
+        code: "PACKAGE_TAGS_MISSING",
+        message: `${workspace.path}/turbo.json is missing package boundary tags.`,
+        file: `${workspace.path}/turbo.json`,
+        is_retriable: false,
+        suggestions: ["Run `boundaries init`."],
+      });
     }
   }
 
   return errors;
 }
 
-function runTurboBoundaries({ root }) {
+function runTurboBoundaries({ root, quiet }) {
   return new Promise((resolve) => {
     const child = spawn("turbo", ["boundaries"], {
       cwd: root,
       shell: process.platform === "win32",
-      stdio: "inherit",
+      stdio: quiet ? ["ignore", "pipe", "pipe"] : "inherit",
     });
+    let stdout = "";
+    let stderr = "";
+
+    if (quiet) {
+      child.stdout?.on("data", (chunk) => {
+        stdout += chunk.toString();
+      });
+      child.stderr?.on("data", (chunk) => {
+        stderr += chunk.toString();
+      });
+    }
 
     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);
+      const problem = {
+        code: "TURBO_NOT_FOUND",
+        message: `could not run \`turbo boundaries\` (${error.message}).`,
+        is_retriable: false,
+        suggestions: ["Install turbo or run `boundaries check --no-turbo`."],
+      };
+      if (!quiet) {
+        process.stderr.write(`boundaries: ${problem.message} ${problem.suggestions[0]}\n`);
+      }
+      resolve({ exitCode: 69, stdout, stderr, error: problem });
     });
 
     child.on("close", (code) => {
-      resolve(code ?? 1);
+      const exitCode = code ?? 1;
+      resolve({
+        exitCode,
+        stdout,
+        stderr,
+        error: exitCode === 0
+          ? undefined
+          : {
+              code: "TURBO_BOUNDARIES_FAILED",
+              message: "`turbo boundaries` reported violations.",
+              is_retriable: false,
+              suggestions: ["Read the captured Turbo output and fix package imports or dependency declarations."],
+            },
+      });
     });
   });
 }

package/src/cli.js

@@ -5,6 +5,15 @@ import { join } from "node:path";
 import { checkRepository } from "./check.js";
 import { evaluateDependency } from "./core.js";
 import { discoverWorkspaces, initRepository } from "./init.js";
+import {
+  EXIT_CODES,
+  failure,
+  hasFlag,
+  stripFlags,
+  success,
+  writeJson,
+} from "./output.js";
+import { commandSchema } from "./schema.js";
 
 const HELP = `Usage: boundaries <command>
 
@@ -17,40 +26,101 @@ Commands:
 
 async function main(argv) {
   const [command, ...args] = argv;
+  const json = hasFlag(argv, "--json");
+  const schema = hasFlag(argv, "--schema");
+
+  if (schema) {
+    writeJson(process.stdout, success(commandSchema));
+    return EXIT_CODES.OK;
+  }
 
   if (!command || command === "help" || command === "--help" || command === "-h") {
+    if (json) {
+      writeJson(process.stdout, success(commandSchema));
+      return EXIT_CODES.OK;
+    }
     process.stdout.write(HELP);
-    return 0;
+    return EXIT_CODES.OK;
   }
 
   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;
+    const result = await initRepository({ dryRun: hasFlag(args, "--dry-run") });
+    if (json) {
+      writeJson(process.stdout, success(summarizeInitResult(result)));
+    } else {
+      process.stdout.write(
+        `${result.dryRun ? "Planned" : "Initialized"} boundaries for ${result.workspaces.length} workspace${result.workspaces.length === 1 ? "" : "s"}.\n`,
+      );
+    }
+    return EXIT_CODES.OK;
   }
 
   if (command === "check") {
     const result = await checkRepository({
       runTurbo: !args.includes("--no-turbo"),
+      quiet: json,
     });
+    if (json) {
+      if (result.ok) {
+        writeJson(process.stdout, success({
+          ok: true,
+          workspaceCount: result.workspaces?.length ?? 0,
+          ranTurbo: !args.includes("--no-turbo"),
+          turbo: result.turbo
+            ? { exitCode: result.turbo.exitCode, stdout: result.turbo.stdout, stderr: result.turbo.stderr }
+            : undefined,
+        }));
+      } else {
+        const primary = result.errors[0] ?? {
+          code: "BOUNDARY_CHECK_FAILED",
+          message: "Boundary check failed.",
+          is_retriable: false,
+          suggestions: ["Inspect command output and retry."],
+        };
+        writeJson(process.stderr, failure(primary, {
+          errors: result.errors,
+          turbo: result.turbo
+            ? { exitCode: result.turbo.exitCode, stdout: result.turbo.stdout, stderr: result.turbo.stderr }
+            : undefined,
+        }));
+      }
+    }
     return result.exitCode;
   }
 
   if (command === "explain") {
-    return explain(args);
+    return explain(stripFlags(args, ["--json"]), { json });
   }
 
-  process.stderr.write(`Unknown command: ${command}\n\n${HELP}`);
-  return 1;
+  const error = {
+    code: "UNKNOWN_COMMAND",
+    message: `Unknown command: ${command}`,
+    is_retriable: false,
+    suggestions: ["Run `boundaries --help` for available commands."],
+  };
+  if (json) {
+    writeJson(process.stderr, failure(error));
+  } else {
+    process.stderr.write(`${error.message}\n\n${HELP}`);
+  }
+  return EXIT_CODES.USAGE;
 }
 
-async function explain(args) {
+async function explain(args, { json = false } = {}) {
   const [fromSelector, toSelector] = args;
   if (!fromSelector || !toSelector) {
-    process.stderr.write("Usage: boundaries explain <from> <to>\n");
-    return 1;
+    const error = {
+      code: "USAGE_ERROR",
+      message: "Usage: boundaries explain <from> <to>",
+      is_retriable: false,
+      suggestions: ["Provide both source and target workspace selectors."],
+    };
+    if (json) {
+      writeJson(process.stderr, failure(error));
+    } else {
+      process.stderr.write(`${error.message}\n`);
+    }
+    return EXIT_CODES.USAGE;
   }
 
   const root = process.cwd();
@@ -61,8 +131,18 @@ async function explain(args) {
   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 error = {
+      code: "WORKSPACE_NOT_FOUND",
+      message: "Could not find both workspaces. Use a package name or workspace path.",
+      is_retriable: false,
+      suggestions: ["Run `boundaries init --dry-run --json` to inspect discovered workspaces."],
+    };
+    if (json) {
+      writeJson(process.stderr, failure(error));
+    } else {
+      process.stderr.write(`${error.message}\n`);
+    }
+    return EXIT_CODES.DATA;
   }
 
   const decision = evaluateDependency({
@@ -73,13 +153,55 @@ async function explain(args) {
     toTags: await readTags(root, to),
   });
 
-  process.stdout.write(
-    `${from.name ?? from.path} -> ${to.name ?? to.path}: ${decision.allowed ? "allowed" : "blocked"}\n${decision.reason}\n`,
-  );
+  const data = {
+    allowed: decision.allowed,
+    reason: decision.reason,
+    from: describeWorkspace(from, await readTags(root, from)),
+    to: describeWorkspace(to, await readTags(root, to)),
+  };
+
+  if (json) {
+    if (decision.allowed) {
+      writeJson(process.stdout, success(data));
+    } else {
+      writeJson(process.stdout, failure({
+        code: "BOUNDARY_BLOCKED",
+        message: decision.reason,
+        is_retriable: false,
+        suggestions: ["Move shared code into a package or adjust package boundary tags intentionally."],
+      }, data));
+    }
+  } else {
+    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 summarizeInitResult(result) {
+  return {
+    dryRun: result.dryRun,
+    workspaces: result.workspaces.map((workspace) => ({
+      name: workspace.name,
+      path: workspace.path,
+    })),
+    plannedWrites: result.plannedWrites.map((write) => ({
+      path: write.path,
+      kind: write.kind,
+    })),
+  };
+}
+
+function describeWorkspace(workspace, tags) {
+  return {
+    name: workspace.name,
+    path: workspace.path,
+    tags,
+  };
+}
+
 function findWorkspace(workspaces, selector) {
   return workspaces.find((workspace) => {
     return workspace.name === selector || workspace.path === selector || workspace.path.endsWith(`/${selector}`);
@@ -107,6 +229,17 @@ main(process.argv.slice(2))
     process.exitCode = exitCode;
   })
   .catch((error) => {
-    process.stderr.write(`boundaries: ${error.message}\n`);
-    process.exitCode = 1;
+    const json = process.argv.includes("--json");
+    const problem = {
+      code: error.code === "ENOENT" ? "FILE_NOT_FOUND" : "UNHANDLED_ERROR",
+      message: error.message,
+      is_retriable: false,
+      suggestions: ["Check that you are running from a workspace root with package.json."],
+    };
+    if (json) {
+      writeJson(process.stderr, failure(problem));
+    } else {
+      process.stderr.write(`boundaries: ${error.message}\n`);
+    }
+    process.exitCode = error.code === "ENOENT" ? EXIT_CODES.DATA : EXIT_CODES.SOFTWARE;
   });

package/src/init.js

@@ -7,29 +7,48 @@ import {
   inferTagsForWorkspace,
 } from "./core.js";
 
-export async function initRepository({ root = process.cwd() } = {}) {
+export async function initRepository({ root = process.cwd(), dryRun = false } = {}) {
   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);
+  const plannedWrites = [];
 
   rootPackageJson.scripts = {
     ...(rootPackageJson.scripts ?? {}),
     boundaries: rootPackageJson.scripts?.boundaries ?? "boundaries check",
   };
 
-  await writeJson(rootPackageJsonPath, rootPackageJson);
-  await writeJson(rootTurboJsonPath, applyRootBoundaryConfig(rootTurboJson));
+  await planJsonWrite({
+    root,
+    filePath: rootPackageJsonPath,
+    value: rootPackageJson,
+    dryRun,
+    plannedWrites,
+  });
+  await planJsonWrite({
+    root,
+    filePath: rootTurboJsonPath,
+    value: applyRootBoundaryConfig(rootTurboJson),
+    dryRun,
+    plannedWrites,
+  });
 
   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));
+    await planJsonWrite({
+      root,
+      filePath: turboJsonPath,
+      value: createPackageTurboConfig(currentTurboJson, tags),
+      dryRun,
+      plannedWrites,
+    });
   }
 
-  return { workspaces };
+  return { dryRun, workspaces, plannedWrites };
 }
 
 export async function discoverWorkspaces(root, rootPackageJson = undefined) {
@@ -162,3 +181,19 @@ async function writeJson(filePath, value) {
   await mkdir(dirname(filePath), { recursive: true });
   await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
 }
+
+async function planJsonWrite({ root, filePath, value, dryRun, plannedWrites }) {
+  plannedWrites.push({
+    path: relativePath(root, filePath),
+    kind: "json",
+    content: `${JSON.stringify(value, null, 2)}\n`,
+  });
+
+  if (!dryRun) {
+    await writeJson(filePath, value);
+  }
+}
+
+function relativePath(root, filePath) {
+  return filePath.startsWith(`${root}/`) ? filePath.slice(root.length + 1) : filePath;
+}

package/src/output.js

@@ -0,0 +1,51 @@
+export const EXIT_CODES = {
+  OK: 0,
+  USAGE: 64,
+  DATA: 65,
+  UNAVAILABLE: 69,
+  SOFTWARE: 70,
+};
+
+export function success(data, metadata = undefined) {
+  return {
+    success: true,
+    data,
+    ...(metadata ? { metadata } : {}),
+  };
+}
+
+export function failure(error, data = undefined) {
+  return {
+    success: false,
+    ...(data ? { data } : {}),
+    error: problem(error),
+  };
+}
+
+export function problem({
+  code,
+  message,
+  is_retriable = false,
+  suggestions = [],
+  file = undefined,
+}) {
+  return {
+    code,
+    message,
+    is_retriable,
+    suggestions,
+    ...(file ? { file } : {}),
+  };
+}
+
+export function writeJson(stream, value) {
+  stream.write(`${JSON.stringify(value)}\n`);
+}
+
+export function hasFlag(args, flag) {
+  return args.includes(flag);
+}
+
+export function stripFlags(args, flags) {
+  return args.filter((arg) => !flags.includes(arg));
+}

package/src/schema.js

@@ -0,0 +1,63 @@
+export const commandSchema = {
+  name: "boundaries",
+  description: "Opinionated Turborepo package boundary conventions.",
+  commands: [
+    {
+      name: "init",
+      description: "Add root Turbo boundary rules and per-package tags.",
+      options: [
+        option("--json", "Print a machine-readable response envelope."),
+        option("--dry-run", "Print planned file writes without changing files."),
+      ],
+      output: "InitResult",
+    },
+    {
+      name: "check",
+      description: "Validate boundary config and optionally run turbo boundaries.",
+      options: [
+        option("--json", "Print a machine-readable response envelope."),
+        option("--no-turbo", "Validate convention config without running turbo boundaries."),
+      ],
+      output: "CheckResult",
+    },
+    {
+      name: "explain",
+      description: "Explain whether one workspace may depend on another.",
+      arguments: [
+        argument("from", "Package name, workspace path, or workspace basename."),
+        argument("to", "Package name, workspace path, or workspace basename."),
+      ],
+      options: [option("--json", "Print a machine-readable response envelope.")],
+      output: "ExplainResult",
+    },
+    {
+      name: "help",
+      description: "Show command help.",
+      options: [
+        option("--json", "Print a machine-readable response envelope."),
+        option("--schema", "Print this command schema as JSON."),
+      ],
+      output: "CommandSchema",
+    },
+  ],
+  responseEnvelope: {
+    success: "boolean",
+    data: "object | undefined",
+    error: "BoundaryProblem | undefined",
+  },
+  errorShape: {
+    code: "string",
+    message: "string",
+    is_retriable: "boolean",
+    suggestions: "string[]",
+    file: "string | undefined",
+  },
+};
+
+function option(name, description) {
+  return { name, description };
+}
+
+function argument(name, description) {
+  return { name, description, required: true };
+}