@agentsfleet/orly 0.10.1 → 0.10.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentsfleet/orly",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "description": "Repository-scoped engineering harness: renders agent rules, materialises the gates that enforce them, and proves the PR boundary \u2014 for any coding agent.",
   "license": "MIT",
   "type": "module",

package/src/config.test.ts

@@ -3,7 +3,7 @@ import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 
-import { CONFIG_PATH, managedDrift, readConfig, readConfigSync, seedConfig, selectPacks, staleVersion, writeConfig } from "./config";
+import { CONFIG_PATH, contentDigest, managedDrift, readConfig, readConfigSync, seedConfig, selectPacks, staleVersion, writeConfig } from "./config";
 import { RulesModel } from "./model";
 
 const ROOT = resolve(import.meta.dir, "..");
@@ -156,6 +156,58 @@ describe("staleVersion", () => {
   });
 });
 
+describe("managedDrift — content", () => {
+  test("a managed file edited after orly wrote it is drift", async () => {
+    // The gap this closes was not hypothetical: a consuming repository added a
+    // gradient ban and a font-ownership check straight to a materialised gate
+    // script, the pack never learned them, and the next update deleted them —
+    // with doctor green the whole way, because it asked only whether the file
+    // EXISTED. A gate whose checks can be removed under a passing verifier is
+    // not a gate.
+    const root = scratch();
+    const wrote = "check_one\ncheck_two\n";
+    writeFileSync(join(root, "audit.sh"), wrote);
+    const config = { ...(await seedConfig(root)), managed: ["audit.sh"], digests: { "audit.sh": contentDigest(new TextEncoder().encode(wrote)) } };
+    expect(managedDrift(root, config)).toEqual([]);
+
+    writeFileSync(join(root, "audit.sh"), "check_one\n");
+    const drift = managedDrift(root, config);
+    expect(drift).toHaveLength(1);
+    expect(drift[0]).toContain("audit.sh");
+    expect(drift[0]).toContain("edited after orly wrote it");
+    // Deliberately NOT "run orly update": the local content may be the better
+    // version, and update discards it. The source is where it has to go.
+    expect(drift[0]).toContain("move the change into the pack source");
+  });
+
+  test("a digest is algorithm-prefixed, and the unprefixed spelling still matches", async () => {
+    // Bare hex is indistinguishable from a credential to an entropy scanner:
+    // gitleaks refused the first commit that carried these, in every consuming
+    // repository at once. The prefix is what makes it pass without a scanner
+    // suppression — and 0.10.2's unprefixed records must not read as drift.
+    const bytes = new TextEncoder().encode("managed\n");
+    const digest = contentDigest(bytes);
+    expect(digest.startsWith("sha256:")).toBe(true);
+
+    const root = scratch();
+    writeFileSync(join(root, "managed.md"), "managed\n");
+    const legacy = { ...(await seedConfig(root)), managed: ["managed.md"], digests: { "managed.md": digest.slice("sha256:".length) } };
+    expect(managedDrift(root, legacy)).toEqual([]);
+
+    const prefixed = { ...legacy, digests: { "managed.md": digest } };
+    expect(managedDrift(root, prefixed)).toEqual([]);
+  });
+
+  test("a file with no recorded digest makes no claim", async () => {
+    // Two cases share this path: a config written before digests existed, and a
+    // hook orly manages but did not author. Neither may be reported as drift.
+    const root = scratch();
+    writeFileSync(join(root, "hook.sh"), "the repository's own\n");
+    const config = { ...(await seedConfig(root)), managed: ["hook.sh"], digests: {} };
+    expect(managedDrift(root, config)).toEqual([]);
+  });
+});
+
 describe("managedDrift", () => {
   test("every managed file present reports no drift", async () => {
     const root = scratch();
@@ -223,6 +275,7 @@ describe("writeConfig", () => {
       commands: { conform: [["make", "audit"]] },
       surfaces: { user: ["src/"], docs: ["docs/"] },
       managed: ["AGENTS.md"],
+      digests: {},
     };
     await writeConfig(root, mine);
     await writeConfig(root, { ...(await readConfig(root))!, orly_version: "0.4.0", managed: ["AGENTS.md", "dispatch/write_rust.md"] });

package/src/config.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, extname, join, relative } from "node:path";
 
@@ -16,6 +17,9 @@ const EXTENSIONS_FIELD = "extensions";
 const PACKS_FIELD = "packs";
 const VERSION_FIELD = "orly_version";
 const MANAGED_FIELD = "managed";
+const DIGESTS_FIELD = "digests";
+const DIGEST_ALGORITHM = "sha256";
+const DIGEST_ENCODING = "hex";
 const COMMANDS_FIELD = "commands";
 const CONFORM_COMMAND = "conform";
 const MAKE_COMMAND = "make";
@@ -65,6 +69,7 @@ export type RepoConfig = {
   commands: Record<string, string[][]>;
   surfaces: JsonObject | undefined;
   managed: string[];
+  digests: Record<string, string>;
 };
 
 export function configPath(targetRoot: string): string {
@@ -109,9 +114,43 @@ function parseConfig(value: JsonObject): RepoConfig {
     commands: readCommands(value[COMMANDS_FIELD]),
     surfaces: isObject(value.surfaces) ? value.surfaces : undefined,
     managed: stringArray(value[MANAGED_FIELD] ?? [], `${CONFIG_PATH} ${MANAGED_FIELD}`),
+    digests: readDigests(value[DIGESTS_FIELD]),
   };
 }
 
+// Absent in a config written before digests existed, and absent per-file for
+// anything orly did not author (a hook it declined to overwrite). Both cases
+// read as "no claim", which is what keeps an older checkout green until its
+// next update rather than failing it for a record it never had.
+function readDigests(value: unknown): Record<string, string> {
+  if (!isObject(value)) return {};
+  const digests: Record<string, string> = {};
+  for (const [path, digest] of Object.entries(value)) if (isString(digest)) digests[path] = digest;
+  return digests;
+}
+
+/// The digest orly records for content it wrote, and recomputes to check it.
+///
+/// Algorithm-prefixed, and not for elegance: a bare 64-character hex string is
+/// indistinguishable from a credential to an entropy-based secret scanner, and
+/// gitleaks refused the very first commit that carried these — in EVERY
+/// consuming repository at once, since `orly update` writes one per managed
+/// file. The prefix is what makes the value self-describing enough to pass,
+/// and the alternative was a scanner suppression, which is how a real
+/// credential eventually rides through.
+export function contentDigest(bytes: Uint8Array): string {
+  return `${DIGEST_ALGORITHM}:${createHash(DIGEST_ALGORITHM).update(bytes).digest(DIGEST_ENCODING)}`;
+}
+
+// Tolerates the unprefixed spelling 0.10.2 wrote for its one release, so a
+// checkout installed on that version is not reported as wholly drifted before
+// its next update — a format change is not an edit, and saying so would be the
+// false alarm that teaches people to ignore the real ones.
+function sameDigest(recorded: string, actual: string): boolean {
+  const bare = (digest: string) => digest.startsWith(`${DIGEST_ALGORITHM}:`) ? digest.slice(DIGEST_ALGORITHM.length + 1) : digest;
+  return bare(recorded) === bare(actual);
+}
+
 // What orly installed here, and whether the engine has moved since.
 export function staleVersion(config: RepoConfig, installedVersion: string): string | undefined {
   if (config.orly_version === installedVersion) return undefined;
@@ -152,9 +191,33 @@ export function managedDrift(targetRoot: string, config: RepoConfig): string[] {
     ...present
       .filter((relativePath) => ignored.has(relativePath))
       .map((relativePath) => `managed file is ignored by git: ${relativePath} — orly wrote it and a clone will not receive it; scope the .gitignore rule that excludes it`),
+    ...editedManaged(targetRoot, config, present),
   ].sort();
 }
 
+// A managed file whose CONTENT no longer matches what orly wrote.
+//
+// The half `managedDrift` was missing, and the gap was not theoretical: a
+// consuming repository added two checks straight to a materialised gate script,
+// the pack never learned them, and the next update deleted them — while doctor
+// reported green throughout, because it verified that the file EXISTED and
+// never that it still said what orly put there. A gate whose checks can be
+// removed under a passing verifier is not a gate.
+//
+// The remedy for a hit is deliberately not `orly update`: the local content may
+// be the better version, as it was in that case. Update overwrites it; the
+// message says to move the change into the source instead, which is the only
+// way it reaches every other consumer.
+function editedManaged(targetRoot: string, config: RepoConfig, present: string[]): string[] {
+  return present.flatMap((relativePath) => {
+    const recorded = config.digests[relativePath];
+    if (!recorded) return [];
+    const actual = contentDigest(readFileSync(join(targetRoot, relativePath)));
+    if (sameDigest(recorded, actual)) return [];
+    return [`managed file was edited after orly wrote it: ${relativePath} — move the change into the pack source, or \`orly update\` to discard it`];
+  });
+}
+
 // Key order is fixed so a rewrite produces a reviewable diff: orly's own two
 // fields sit at the ends, the repository's three in the middle, untouched.
 export async function writeConfig(targetRoot: string, config: RepoConfig): Promise<string> {
@@ -168,6 +231,7 @@ export async function writeConfig(targetRoot: string, config: RepoConfig): Promi
     commands: config.commands,
     ...(config.surfaces ? { surfaces: config.surfaces } : {}),
     managed: [...config.managed].sort(),
+    digests: Object.fromEntries(Object.entries(config.digests).sort(([a], [b]) => a.localeCompare(b))),
   };
   await Bun.write(path, `${JSON.stringify(ordered, undefined, JSON_INDENT)}${NEWLINE}`);
   return path;
@@ -177,7 +241,7 @@ export async function writeConfig(targetRoot: string, config: RepoConfig): Promi
 // from what the repository already builds with; an empty set is honest rather
 // than wrong, and says so in the gate's own failure message.
 export async function seedConfig(targetRoot: string): Promise<RepoConfig> {
-  return { schema_version: CONFIG_SCHEMA_VERSION, orly_version: "", packs: [], commands: await sniffCommands(targetRoot), surfaces: undefined, managed: [] };
+  return { schema_version: CONFIG_SCHEMA_VERSION, orly_version: "", packs: [], commands: await sniffCommands(targetRoot), surfaces: undefined, managed: [], digests: {} };
 }
 
 // What this repository installed and runs with, read from its own `.oracle/`.

package/src/install.ts

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, mkdtempSync, readdirSync, realpathSync, renameSy
 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 { CONFIG_PATH, contentDigest, readConfig, seedConfig, selectPacks, writeConfig } from "./config";
 import { applyMode, assertWritableInside, hashContent, isBelow, isString, JsonObject, modeLabel, objectArray, objectValue, OrlyError, RulesModel, stringArray } from "./model";
 import { AGENTS_FILENAME, GENERATED_BANNER, installLoaders, Layout, loaderTargets, ORLY_AGENTS_FILENAME } from "./loaders";
 import { referenceClosureErrors, renderProfileText } from "./references";
@@ -116,7 +116,16 @@ export async function install(model: RulesModel, options: InstallOptions): Promi
   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] });
+  // Digests cover `planned` only. Hooks are managed — orly restores a missing
+  // one — but it does not always AUTHOR them: it refuses to overwrite a hook it
+  // did not write. Recording a digest for a file whose content belongs to the
+  // repository would report the repository's own edits as drift.
+  await writeConfig(targetRoot, {
+    ...config,
+    orly_version: options.orlyVersion,
+    managed: [...planned.map((file) => file.target), ...hooks.all],
+    digests: Object.fromEntries(planned.map((file) => [file.target, contentDigest(file.content)])),
+  });
   if (!existing) written.push(CONFIG_PATH);
   return { ok: true, packs, written: written.sort(), skipped: skipped.sort(), errors: [] };
 }
@@ -370,6 +379,11 @@ function retargetRulesCitations(text: string, orlyFile: string): string {
   return text
     .replaceAll(`](${AGENTS_FILENAME})`, `](${orlyFile})`)
     .replaceAll(`](../${AGENTS_FILENAME})`, `](../${orlyFile})`)
+    // The relative spelling first: `../AGENTS.md` contains `AGENTS.md`, so the
+    // bare rule below would rewrite its tail and leave the `../` stranded.
+    // Missing it is what rendered `[`../AGENTS.md`](../AGENTS.orly.md)` into
+    // four managed pages — a label naming one file over a link to another.
+    .replaceAll(`\`../${AGENTS_FILENAME}\``, `\`../${orlyFile}\``)
     .replaceAll(`\`${AGENTS_FILENAME}\``, `\`${orlyFile}\``);
 }