@agentsfleet/orly 0.5.0

package/src/install.ts

@@ -0,0 +1,447 @@
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, realpathSync, renameSync, rmSync } from "node:fs";
+import { dirname, extname, join, relative, resolve } from "node:path";
+
+import { UNSCOPED_ENVIRONMENT } from "./git_env";
+import { CONFIG_PATH, readConfig, seedConfig, selectPacks, writeConfig } from "./config";
+import { applyMode, assertWritableInside, hashContent, isBelow, isString, JsonObject, modeLabel, objectArray, objectValue, OrlyError, RulesModel, stringArray } from "./model";
+import { referenceClosureErrors, renderProfileText } from "./references";
+import { Renderer } from "./render";
+
+const AGENTS_FILENAME = "AGENTS.md";
+const ORLY_AGENTS_FILENAME = "AGENTS.orly.md";
+const GENERATED_BANNER = "> **Generated by `orly`.**";
+const NEWLINE = "\n";
+const POINTER_OPEN = "<!-- orly:begin -->";
+const POINTER_CLOSE = "<!-- orly:end -->";
+const HOOKS_DIRECTORY = ".githooks";
+const REGISTRY_PACKS_LABEL = "registry packs";
+const STAGE_PREFIX = "orly-install-";
+const MARKDOWN_EXTENSION = ".md";
+const SKILLS_SEGMENT = "/skills/";
+const MODE_EXECUTABLE = "0755";
+const MODE_REGULAR = "0644";
+const GIT_COMMAND = "git";
+const GIT_REPO_FLAG = "-C";
+const PIPE_OUTPUT = "pipe";
+const HOOK_GATES = [["pre-commit", "work"], ["pre-push", "verify"]] as const;
+const GIT_CONFIG_SUBCOMMAND = "config";
+const HOOKS_PATH_KEY = "core.hooksPath";
+const MANAGED_FILE_KIND = "managed file";
+const HOOK_KIND = "hook";
+const POINTER_HOST_KIND = "pointer host";
+
+export type InstallError = { path: string; message: string; suggestion: string };
+
+export type InstallResult = {
+  ok: boolean;
+  packs: string[];
+  written: string[];
+  skipped: string[];
+  errors: InstallError[];
+};
+
+export type InstallOptions = {
+  targetRoot: string;
+  force: boolean;
+  installHooks: boolean;
+  orlyVersion: string;
+};
+
+type PlannedFile = { target: string; content: Uint8Array; mode: string };
+
+// Materialise a profile into a repository: its rules, the gates that enforce
+// them, the hooks that run the gates, and a lock recording exactly what landed.
+// Everything is staged in a temporary directory first, so a run that refuses —
+// or dies — leaves the target untouched rather than half-installed.
+export async function install(model: RulesModel, options: InstallOptions): Promise<InstallResult> {
+  const targetRoot = resolve(options.targetRoot);
+  requireWorkTree(targetRoot);
+  const existing = await readConfig(targetRoot);
+  const config = existing ?? await seedConfig(targetRoot);
+  const packs = selectPacks(model, targetRoot, config.packs, new Set(config.managed));
+
+  const layout = resolveLayout(model, targetRoot);
+  const planned = await planFiles(model, packs, config.commands, targetRoot, layout.orlyFile);
+  const managed = new Set(config.managed);
+  const refusals: InstallError[] = [];
+  const written: string[] = [];
+  const skipped: string[] = [];
+
+  for (const file of planned) {
+    const escape = escapesTarget(targetRoot, file.target, MANAGED_FILE_KIND);
+    if (escape) { refusals.push(escape); continue; }
+    const path = join(targetRoot, file.target);
+    if (!existsSync(path)) { written.push(file.target); continue; }
+    // Already exactly what this run would write — leave it and say so.
+    if (hashContent(await Bun.file(path).bytes()) === hashContent(file.content) && modeLabel(path) === file.mode) { skipped.push(file.target); continue; }
+    // The lock is the record of authorship: a file orly wrote is orly's to
+    // replace, and git shows the replacement before it is committed. A file
+    // orly never wrote belongs to the repository and is never touched silently.
+    if (options.force || managed.has(file.target)) { written.push(file.target); continue; }
+    // The generated banner is authorship evidence in its own right, and the
+    // only evidence available for a repository installed before managed[]
+    // tracked anything — this checkout among them. Without it, orly's own
+    // render reads as a stranger's file and every update refuses.
+    if (file.target === layout.orlyFile && (await Bun.file(path).text()).startsWith(GENERATED_BANNER)) { written.push(file.target); continue; }
+    refusals.push(refusal(file.target, false));
+  }
+  if (options.installHooks) {
+    const claim = hooksClaimedByAnother(targetRoot);
+    if (claim && !options.force) refusals.push(claim);
+    for (const [name, gate] of HOOK_GATES) {
+      const target = `${HOOKS_DIRECTORY}/${name}`;
+      const escape = escapesTarget(targetRoot, target, HOOK_KIND);
+      if (escape) { refusals.push(escape); continue; }
+      const authorship = await hookAuthorship(targetRoot, target, gate, managed, options.force);
+      if (authorship) refusals.push(authorship);
+    }
+  }
+  const configEscape = escapesTarget(targetRoot, CONFIG_PATH, "config");
+  if (configEscape) refusals.push(configEscape);
+  // The pointer host is a write like any other, and the only one orly aims at
+  // a file it does not own — so it needs the guard most, not least. A committed
+  // AGENTS.md symlink pointing outside the repository otherwise carried the
+  // block wherever the link led, and reported it as an ordinary success.
+  if (layout.pointerHost) {
+    const hostEscape = escapesTarget(targetRoot, layout.pointerHost, POINTER_HOST_KIND);
+    if (hostEscape) refusals.push(hostEscape);
+  }
+  if (refusals.length > 0) return { ok: false, packs, written: [], skipped, errors: refusals };
+
+  const closure = await stageAndCommit(model, targetRoot, planned, written);
+  if (closure.length > 0) return { ok: false, packs, written: [], skipped, errors: closure };
+
+  // After the managed files land, so a repository whose install refused for any
+  // other reason never carries a pointer to rules that were not written.
+  if (layout.pointerHost && await upsertPointer(targetRoot, layout.pointerHost, layout.orlyFile)) written.push(layout.pointerHost);
+  const hooks = options.installHooks ? await installHooks(targetRoot) : { written: [], all: [] };
+  written.push(...hooks.written);
+  skipped.push(...hooks.all.filter((path) => !hooks.written.includes(path)));
+  // One file carries both halves: the repository's own fields pass through
+  // untouched, orly's two record what this run installed and wrote.
+  await writeConfig(targetRoot, { ...config, orly_version: options.orlyVersion, managed: [...planned.map((file) => file.target), ...hooks.all] });
+  if (!existing) written.push(CONFIG_PATH);
+  return { ok: true, packs, written: written.sort(), skipped: skipped.sort(), errors: [] };
+}
+
+// A committed symlink inside the target repository — planted by that
+// repository's own author, not the person running init — otherwise lets a
+// managed-file or hook write follow it and land anywhere the invoking user
+// can write. Checked up front, before anything is staged, so it reports as
+// a normal refusal rather than a mid-write failure; assertWritableInside
+// runs again at the actual write as a last-line guard against a target
+// that changed underneath the run.
+function escapesTarget(targetRoot: string, target: string, kind: string): InstallError | undefined {
+  try {
+    assertWritableInside(targetRoot, target, kind);
+    return undefined;
+  } catch (error) {
+    return { path: target, message: error instanceof Error ? error.message : String(error), suggestion: "remove or fix the symlink in the target repository before installing" };
+  }
+}
+
+// A hook is a managed file that happens to be generated rather than copied, and
+// it earns the same authorship rule: one orly wrote is orly's to replace, one
+// the repository wrote is the repository's. Without this, installHooks wrote
+// unconditionally — a repository whose own pre-commit ran its test suite lost
+// it to `orly init` silently, counted as an ordinary write in the success line.
+async function hookAuthorship(targetRoot: string, target: string, gate: string, managed: Set<string>, force: boolean): Promise<InstallError | undefined> {
+  if (force || managed.has(target)) return undefined;
+  const path = join(targetRoot, target);
+  if (!existsSync(path)) return undefined;
+  // Byte-identical to what this run would write: an install that predates hook
+  // tracking, not someone else's hook. Replacing it changes nothing.
+  if ((await Bun.file(path).text()) === hookScript(gate)) return undefined;
+  return { path: target, message: "a hook already exists here and orly did not write it", suggestion: "move it aside, re-run with --force to replace it, or use --no-hooks" };
+}
+
+function refusal(target: string, wasManaged: boolean): InstallError {
+  return wasManaged
+    ? { path: target, message: "managed file was edited in place since it was installed", suggestion: "revert the edit, or re-run with --force to overwrite it" }
+    : { path: target, message: "a file already exists here and orly did not write it", suggestion: "move it aside, or re-run with --force to replace it" };
+}
+
+// The payload is written to a scratch directory and only moved into the target
+// once every file exists and every reference it names resolves. Reference
+// closure runs against the staged tree, so a pack whose façade cites a document
+// no selected pack provides is caught before anything lands. The scratch
+// directory lives inside the target's own .oracle/ — not the OS tmp dir —
+// because `rename(2)` cannot cross a filesystem boundary: an OS tmp dir and
+// the target repository are routinely on different filesystems (a mounted
+// external drive, a devcontainer's bind-mounted workspace over a tmpfs
+// /tmp), and staging there turned every such install into a hard EXDEV
+// crash instead of the atomic move this function exists to guarantee.
+async function stageAndCommit(model: RulesModel, targetRoot: string, planned: PlannedFile[], written: string[]): Promise<InstallError[]> {
+  const stagingParent = join(targetRoot, dirname(CONFIG_PATH));
+  const stagingParentExisted = existsSync(stagingParent);
+  mkdirSync(stagingParent, { recursive: true });
+  const stage = mkdtempSync(join(stagingParent, STAGE_PREFIX));
+
+  // A refusal must leave the target exactly as it found it, and staging now
+  // lives inside it: remove .oracle/ too if this run is the one that created
+  // it and it is still empty on the failure path — a fresh empty directory
+  // left behind is as much a footprint as a written file. The success path
+  // must NOT run this: .oracle/ is still empty at this point (the caller
+  // writes orly.json into it right after stageAndCommit returns), so an
+  // unconditional check would delete a directory the next step needs.
+  const cleanupStagingParentIfEmpty = () => {
+    rmSync(stage, { recursive: true, force: true });
+    if (!stagingParentExisted && existsSync(stagingParent) && readdirSync(stagingParent).length === 0) rmSync(stagingParent, { recursive: true, force: true });
+  };
+
+  try {
+    for (const file of planned) {
+      const path = join(stage, file.target);
+      mkdirSync(dirname(path), { recursive: true });
+      await Bun.write(path, file.content);
+      applyMode(path, file.mode);
+    }
+    // Skills are playbooks copied verbatim, not rule pages: one names the
+    // façade for every language it might be invoked in. Grading those citations
+    // would force a Go repository to take the Zig and TypeScript packs to
+    // satisfy a menu it will never read — the same reason a `docs/TEMPLATE.md`
+    // comment is exempt.
+    const markdown = planned
+      .filter((file) => extname(file.target) === MARKDOWN_EXTENSION && !file.target.includes(SKILLS_SEGMENT))
+      .map((file) => join(stage, file.target));
+    const missing = await referenceClosureErrors(stage, markdown, targetRoot);
+    if (missing.length > 0) {
+      cleanupStagingParentIfEmpty();
+      return missing.map((message) => ({ path: AGENTS_FILENAME, message, suggestion: "select the pack that provides the cited file, or amend the citation" }));
+    }
+
+    const targets = new Set(written);
+    for (const file of planned.filter((candidate) => targets.has(candidate.target))) {
+      assertWritableInside(targetRoot, file.target, MANAGED_FILE_KIND);
+      const destination = join(targetRoot, file.target);
+      mkdirSync(dirname(destination), { recursive: true });
+      renameSync(join(stage, file.target), destination);
+      applyMode(destination, file.mode);
+    }
+    rmSync(stage, { recursive: true, force: true });
+    return [];
+  } catch (error) {
+    cleanupStagingParentIfEmpty();
+    throw error;
+  }
+}
+
+// A hooksPath already pointing somewhere other than what init installs is
+// someone else's setup — retargeting it silently would disable whatever
+// ran there before. init only overrides its own prior installs (the same
+// directory name) or an unset config, matching the idempotent-rerun case.
+function hooksClaimedByAnother(targetRoot: string): InstallError | undefined {
+  const result = Bun.spawnSync([GIT_COMMAND, GIT_REPO_FLAG, targetRoot, GIT_CONFIG_SUBCOMMAND, "--get", HOOKS_PATH_KEY], { stdout: PIPE_OUTPUT, stderr: PIPE_OUTPUT, env: UNSCOPED_ENVIRONMENT });
+  if (result.exitCode !== 0) return undefined;
+  const existing = result.stdout.toString().trim();
+  if (existing === "" || existing === HOOKS_DIRECTORY) return undefined;
+  return { path: HOOKS_PATH_KEY, message: `already set to '${existing}', not the directory this install manages`, suggestion: "run with --no-hooks to leave it alone, or --force to retarget it" };
+}
+
+// Hooks are generated, never copied: this repository's own hooks run `make
+// audit` and `bin/orly verify`, neither of which exists in a consumer. What a
+// consumer needs is the gate engine, reached through the binary that installed
+// it — with a PATH fallback so a relocated checkout still resolves.
+async function installHooks(targetRoot: string): Promise<{ written: string[]; all: string[] }> {
+  for (const [name] of HOOK_GATES) assertWritableInside(targetRoot, `${HOOKS_DIRECTORY}/${name}`, HOOK_KIND);
+  const directory = join(targetRoot, HOOKS_DIRECTORY);
+  mkdirSync(directory, { recursive: true });
+  const written: string[] = [];
+  const all: string[] = [];
+  for (const [name, gate] of HOOK_GATES) {
+    const path = join(directory, name);
+    const script = hookScript(gate);
+    all.push(`${HOOKS_DIRECTORY}/${name}`);
+    if (existsSync(path) && (await Bun.file(path).text()) === script && modeLabel(path) === MODE_EXECUTABLE) continue;
+    await Bun.write(path, script);
+    applyMode(path, MODE_EXECUTABLE);
+    written.push(`${HOOKS_DIRECTORY}/${name}`);
+  }
+  runGit(targetRoot, [GIT_CONFIG_SUBCOMMAND, HOOKS_PATH_KEY, HOOKS_DIRECTORY]);
+  return { written, all };
+}
+
+function hookScript(gate: string): string {
+  return [
+    "#!/usr/bin/env bash",
+    "# Generated by orly. Re-run `orly init` to refresh.",
+    "set -euo pipefail",
+    "",
+    "# git exports these to every hook; inherited by a spawned git they pin it to",
+    "# the hook's repository instead of the one being judged.",
+    "unset GIT_DIR GIT_INDEX_FILE GIT_WORK_TREE GIT_COMMON_DIR GIT_PREFIX \\",
+    "      GIT_OBJECT_DIRECTORY GIT_ALTERNATE_OBJECT_DIRECTORIES",
+    "",
+    'if ! command -v orly >/dev/null 2>&1; then',
+    '    printf "orly: not on PATH — install it with `bun add -g @agentsfleet/orly`, or delete this hook\\n" >&2',
+    "    exit 1",
+    "fi",
+    "",
+    `exec orly gate ${gate}`,
+    "",
+  ].join("\n");
+}
+
+
+// One entry per target, so two packs naming the same file collapse instead of
+// racing. Two packs naming DIFFERENT sources for one target is a registry bug
+// and stops the install rather than letting pack order decide the winner.
+async function planFiles(model: RulesModel, packs: string[], commands: Record<string, string[][]>, targetRoot: string, orlyFile: string): Promise<PlannedFile[]> {
+  const registryPacks = objectValue(model.registry.packs, REGISTRY_PACKS_LABEL);
+  const known = new Set(Object.keys(registryPacks));
+  const planned = new Map<string, PlannedFile>();
+  const sources = new Map<string, string>();
+  for (const name of packs) {
+    const pack = objectValue(registryPacks[name], `pack ${name}`);
+    for (const entry of objectArray(pack.managed_files, `pack ${name} managed_files`)) {
+      if (!isString(entry.source) || !isString(entry.target)) throw new OrlyError(`pack ${name} managed file must carry string source and target`);
+      const claimed = sources.get(entry.target);
+      if (claimed && claimed !== entry.source) throw new OrlyError(`packs disagree on ${entry.target}: ${claimed} and ${entry.source}`);
+      sources.set(entry.target, entry.source);
+      const path = join(model.root, entry.source);
+      // Installing into the checkout that owns the sources. Copying is for
+      // consumers: here the repository already has the file, and writing it
+      // would either replace a pack source with its own pack-filtered
+      // rendering (same path) or plant a second copy that drifts from the
+      // original (skills/ into .claude/skills/). Skipping is what the retired
+      // sync verb used to buy, generalised past the same-path case.
+      if (resolved(model.root) === resolved(targetRoot)) continue;
+      planned.set(entry.target, { target: entry.target, content: await managedContent(path, entry.target, entry.source, packs, known, orlyFile), mode: modeLabel(path) });
+    }
+  }
+  const rendered = await new Renderer(model).renderText(packs, commands);
+  planned.set(orlyFile, { target: orlyFile, content: new TextEncoder().encode(rendered), mode: MODE_REGULAR });
+  return [...planned.values()].sort((left, right) => left.target.localeCompare(right.target));
+}
+
+// Where orly's rules land, and whether the repository keeps a file of its own.
+//
+// A repository that already wrote an AGENTS.md keeps it, under its own name,
+// byte for byte — orly's rules go beside it as AGENTS.orly.md and are reached
+// by a pointer block. Renaming their file would put orly's name on content it
+// did not write and move a file its own docs already cite. A repository with
+// no AGENTS.md gets orly's rules under that name directly, because nothing is
+// displaced and agent runtimes auto-load it.
+//
+// The test is the generated banner, not the config's managed list: this
+// checkout's own .oracle/orly.json predates managed tracking, so a
+// managed-based test would treat orly's own render as a stranger's file and
+// push it aside on the next update.
+function resolveLayout(model: RulesModel, targetRoot: string): { orlyFile: string; pointerHost?: string } {
+  // The checkout that authors the rules holds them as sources, not as an
+  // installed copy — the same reason pack files inside the target are skipped
+  // rather than written. Its AGENTS.md IS the render, and the payload ships it
+  // as the reference copy.
+  if (resolved(model.root) === resolved(targetRoot)) return { orlyFile: AGENTS_FILENAME };
+  // Everywhere else orly is a guest. It always takes AGENTS.orly.md and always
+  // leaves AGENTS.md to the repository, whether or not the repository has
+  // written one yet. One layout, so `update` never has to ask which mode it is
+  // in, and a repository that starts with no rules of its own still has the
+  // file to put them in when it wants them.
+  return { orlyFile: ORLY_AGENTS_FILENAME, pointerHost: AGENTS_FILENAME };
+}
+
+// The one edit orly makes to a file it does not own. Delimited so a re-run
+// replaces exactly what the last run wrote and nothing either side of it, and
+// so a user who wants orly out can delete the block by sight.
+function pointerBlock(orlyFile: string): string {
+  return [
+    POINTER_OPEN,
+    `**Engineering harness:** read [\`${orlyFile}\`](${orlyFile}) as well — it carries the safety rules,`,
+    "the dispatch router that names which rule page to read before which edit, and the lifecycle",
+    "this repository gates on. Where the two disagree, this file wins.",
+    POINTER_CLOSE,
+  ].join(NEWLINE);
+}
+
+// What a repository with no rules of its own starts with: the pointer, and a
+// visible invitation to write here. Without the second line the stub reads as
+// an orly artifact and nobody touches it — which is the trap the single-file
+// layout had, moved one file over.
+function stubHost(block: string): string {
+  return [
+    "# Repository rules",
+    "",
+    block,
+    "",
+    "Write this repository's own rules below. orly never edits this file",
+    "outside the block above, so nothing here is lost to an `orly update`.",
+  ].join(NEWLINE);
+}
+
+async function upsertPointer(targetRoot: string, host: string, orlyFile: string): Promise<boolean> {
+  // Re-checked at the write, as every other destination is: the up-front
+  // refusal pass guards the plan, this guards the target that could have
+  // changed underneath the run.
+  assertWritableInside(targetRoot, host, POINTER_HOST_KIND);
+  const path = join(targetRoot, host);
+  const block = pointerBlock(orlyFile);
+  // No file, or one orly generated under an older layout where it owned this
+  // name. Neither holds a line the repository wrote, so both become the stub —
+  // which is the migration for anything installed before the split.
+  if (!existsSync(path) || (await Bun.file(path).text()).startsWith(GENERATED_BANNER)) {
+    await Bun.write(path, `${stubHost(block)}\n`);
+    return true;
+  }
+  const current = await Bun.file(path).text();
+  const open = current.indexOf(POINTER_OPEN);
+  const close = current.indexOf(POINTER_CLOSE);
+  if (open >= 0 && close > open) {
+    const replaced = `${current.slice(0, open)}${block}${current.slice(close + POINTER_CLOSE.length)}`;
+    if (replaced === current) return false;
+    await Bun.write(path, replaced);
+    return true;
+  }
+  await Bun.write(path, `${current.replace(/\s*$/, "")}\n\n${block}\n`);
+  return true;
+}
+
+function resolved(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+// Managed markdown is pack-filtered on the way in, exactly as a rendered core
+// document is. Copying it raw is how a Rust crate ends up holding a rule that
+// points at a Zig façade it will never receive.
+async function managedContent(path: string, target: string, source: string, packs: string[], known: Set<string>, orlyFile: string): Promise<Uint8Array> {
+  const bytes = await Bun.file(path).bytes();
+  if (extname(target) !== MARKDOWN_EXTENSION) return bytes;
+  const filtered = renderProfileText(new TextDecoder().decode(bytes), new Set(packs), known, source);
+  return new TextEncoder().encode(`${retargetRulesCitations(filtered, orlyFile)}\n`);
+}
+
+// A rule page citing `AGENTS.md` means orly's rules, which is that file's name
+// only in the checkout that authors them. In a consumer they live in
+// AGENTS.orly.md and AGENTS.md belongs to the repository, so a citation left
+// alone would point every reader at the wrong half — and fail reference
+// closure, since the repository's own file is not orly's to promise.
+function retargetRulesCitations(text: string, orlyFile: string): string {
+  if (orlyFile === AGENTS_FILENAME) return text;
+  return text
+    .replaceAll(`](${AGENTS_FILENAME})`, `](${orlyFile})`)
+    .replaceAll(`](../${AGENTS_FILENAME})`, `](../${orlyFile})`)
+    .replaceAll(`\`${AGENTS_FILENAME}\``, `\`${orlyFile}\``);
+}
+
+// git canonicalises symlinks in --show-toplevel; targetRoot, as handed in by
+// a caller, usually has not been (macOS puts $TMPDIR and often the caller's
+// own working directory behind one). Comparing without resolving both sides
+// made every install from a symlinked path — routine on macOS — refuse with
+// "not the repository root" against its own root.
+function requireWorkTree(targetRoot: string): void {
+  if (!existsSync(targetRoot)) throw new OrlyError(`target directory does not exist: ${targetRoot}`);
+  const result = Bun.spawnSync([GIT_COMMAND, GIT_REPO_FLAG, targetRoot, "rev-parse", "--show-toplevel"], { stdout: PIPE_OUTPUT, stderr: PIPE_OUTPUT, env: UNSCOPED_ENVIRONMENT });
+  if (result.exitCode !== 0) throw new OrlyError(`not a git repository: ${targetRoot} — run \`git init\` first`);
+  const top = resolve(result.stdout.toString().trim());
+  const resolvedTarget = realpathSync(targetRoot);
+  if (top !== resolvedTarget) throw new OrlyError(`install at the repository root, not a subdirectory: ${relative(top, resolvedTarget)}`);
+}
+
+function runGit(targetRoot: string, args: string[]): void {
+  const result = Bun.spawnSync([GIT_COMMAND, GIT_REPO_FLAG, targetRoot, ...args], { stdout: PIPE_OUTPUT, stderr: PIPE_OUTPUT, env: UNSCOPED_ENVIRONMENT });
+  if (result.exitCode !== 0) throw new OrlyError(`git ${args.join(" ")} failed: ${result.stderr.toString().trim()}`);
+}

package/src/install_nested.test.ts

@@ -0,0 +1,32 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { cleanupTemporaryDirectories, newRepository } from "./gates_test_support";
+import { install } from "./install";
+import { RulesModel } from "./model";
+
+afterEach(cleanupTemporaryDirectories);
+
+describe("install package location", () => {
+  test("materialises managed files when the engine package is nested in a consumer repository", async () => {
+    const repo = newRepository();
+    const engineRoot = join(repo, "node_modules", "@agentsfleet", "orly");
+    mkdirSync(engineRoot, { recursive: true });
+    await Bun.write(join(engineRoot, "core.md"), "core\n");
+    await Bun.write(join(engineRoot, "rules.md"), "fixture rules\n");
+
+    const model = new RulesModel(engineRoot, {
+      schema_version: 1,
+      core_documents: ["core.md"],
+      packs: { base: { extensions: [], managed_files: [{ source: "rules.md", target: "rules.md" }] } },
+      rules: [],
+    });
+
+    const result = await install(model, { targetRoot: repo, force: false, installHooks: false, orlyVersion: "0.5.0" });
+
+    expect(result.ok).toBe(true);
+    expect(result.written).toContain("rules.md");
+    expect(await Bun.file(join(repo, "rules.md")).text()).toBe("fixture rules\n");
+  });
+});

package/src/model.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, test } from "bun:test";
+import { resolve } from "node:path";
+
+import { readJsonObject, RulesModel } from "./model";
+
+const ROOT = resolve(import.meta.dir, "..");
+
+describe("RulesModel", () => {
+  test("validates the current registry", async () => {
+    const model = await RulesModel.load(ROOT);
+
+    expect(() => model.validate()).not.toThrow();
+  });
+
+  test("rejects the declared invalid registry fixture", async () => {
+    const registry = await readJsonObject(resolve(ROOT, "fixtures/registry-invalid.json"));
+    const model = new RulesModel(ROOT, registry);
+
+    expect(() => model.validate()).toThrow();
+  });
+
+  test("rejects missing mechanical rule fixtures", async () => {
+    const source = await RulesModel.load(ROOT);
+    const registry = structuredClone(source.registry);
+    if (!Array.isArray(registry.rules) || typeof registry.rules[0] !== "object" || registry.rules[0] === null) throw new Error("mechanical rule missing");
+    registry.rules[0] = { ...registry.rules[0], fixtures: { pass: ["fixtures/missing.json"], fail: ["fixtures/registry-invalid.json"] } };
+    const model = new RulesModel(source.root, registry);
+
+    expect(() => model.validate()).toThrow("fixture source is missing");
+  });
+});