@danieljvdm/dev-kit 0.6.0 → 0.7.1

package/src/node-symbolic-link.ts

@@ -9,6 +9,7 @@ export type SymbolicLinkObservation =
 const isNotSymbolicLink = (error: PlatformError.PlatformError): boolean => {
   if (error.reason._tag !== "Unknown") return false;
   const cause = error.reason.cause;
+
   return cause instanceof Error && "code" in cause && cause.code === "EINVAL";
 };
 
@@ -16,6 +17,7 @@ export const observeSymbolicLink = Effect.fn("observeSymbolicLink")(function* (
   absolutePath: string,
 ) {
   const fs = yield* FileSystem.FileSystem;
+
   return yield* fs.readLink(absolutePath).pipe(
     Effect.map((target): SymbolicLinkObservation => ({ kind: "symlink", target })),
     Effect.catch((error) => {
@@ -25,6 +27,7 @@ export const observeSymbolicLink = Effect.fn("observeSymbolicLink")(function* (
       if (isNotSymbolicLink(error)) {
         return Effect.succeed<SymbolicLinkObservation>({ kind: "not-symlink" });
       }
+
       return Effect.fail(error);
     }),
   );

package/src/oxlint-plugin-effect.js

@@ -33,6 +33,7 @@ const noPromiseAtomMode = {
         const isMode =
           (key.type === "Identifier" && key.name === "mode") ||
           (key.type === "Literal" && key.value === "mode");
+
         if (isMode && value.type === "Literal" && value.value === "promise") {
           context.report({ node, messageId: "noPromiseAtomMode" });
         }
@@ -117,8 +118,10 @@ const noAsyncWorkflow = {
         parent?.type === "Property" &&
         ((parent.key.type === "Identifier" && parent.key.name === "try") ||
           (parent.key.type === "Literal" && parent.key.value === "try"));
+
       if (!isCapturedTryThunk) context.report({ node, messageId: "noAsyncWorkflow" });
     };
+
     return {
       ArrowFunctionExpression: check,
       FunctionDeclaration: check,

package/src/oxlint-plugin-style.d.ts

@@ -0,0 +1,8 @@
+declare const styleOxlintPlugin: {
+  readonly meta: { readonly name: "dev-kit-style" };
+  readonly rules: {
+    readonly "padding-line-between-statements": unknown;
+  };
+};
+
+export default styleOxlintPlugin;

package/src/oxlint-plugin-style.js

@@ -0,0 +1,8 @@
+import stylisticPlugin from "@stylistic/eslint-plugin";
+
+export default {
+  meta: { name: "dev-kit-style" },
+  rules: {
+    "padding-line-between-statements": stylisticPlugin.rules["padding-line-between-statements"],
+  },
+};

package/src/oxlint.js

@@ -13,6 +13,10 @@ export const recommendedOxlintConfig = {
       name: "effect",
       specifier: "@danieljvdm/dev-kit/oxlint-plugin-effect",
     },
+    {
+      name: "stylistic",
+      specifier: "@danieljvdm/dev-kit/oxlint-plugin-style",
+    },
   ],
   plugins: ["import", "react", "vitest"],
   rules: {
@@ -24,6 +28,16 @@ export const recommendedOxlintConfig = {
     "import/no-self-import": "error",
     "react/exhaustive-deps": "error",
     "react/rules-of-hooks": "error",
+    "stylistic/padding-line-between-statements": [
+      "error",
+      { blankLine: "always", prev: ["const", "let", "var"], next: "*" },
+      {
+        blankLine: "any",
+        prev: ["const", "let", "var"],
+        next: ["const", "let", "var"],
+      },
+      { blankLine: "always", prev: "*", next: "return" },
+    ],
     "typescript/consistent-type-imports": "error",
     "typescript/no-floating-promises": "off",
     "typescript/no-explicit-any": "error",

package/src/oxlint.ts

@@ -16,6 +16,10 @@ export const recommendedOxlintConfig = {
       name: "effect",
       specifier: "@danieljvdm/dev-kit/oxlint-plugin-effect",
     },
+    {
+      name: "stylistic",
+      specifier: "@danieljvdm/dev-kit/oxlint-plugin-style",
+    },
   ],
   plugins: ["import", "react", "vitest"],
   rules: {
@@ -27,6 +31,16 @@ export const recommendedOxlintConfig = {
     "import/no-self-import": "error",
     "react/exhaustive-deps": "error",
     "react/rules-of-hooks": "error",
+    "stylistic/padding-line-between-statements": [
+      "error",
+      { blankLine: "always", prev: ["const", "let", "var"], next: "*" },
+      {
+        blankLine: "any",
+        prev: ["const", "let", "var"],
+        next: ["const", "let", "var"],
+      },
+      { blankLine: "always", prev: "*", next: "return" },
+    ],
     "typescript/consistent-type-imports": "error",
     "typescript/no-floating-promises": "off",
     "typescript/no-explicit-any": "error",

package/src/package-skill-source.ts

@@ -25,65 +25,88 @@ export type DiscoveredPackageSkill = {
   readonly linkPath: string;
 };
 
-const PackageMetadataSchema = Schema.fromJsonString(Schema.Struct({
-  name: Schema.String,
-  version: Schema.String,
-  intent: Schema.optional(Schema.Unknown),
-  repository: Schema.optional(Schema.Unknown),
-}));
+const PackageMetadataSchema = Schema.fromJsonString(
+  Schema.Struct({
+    name: Schema.String,
+    version: Schema.String,
+    intent: Schema.optional(Schema.Unknown),
+    repository: Schema.optional(Schema.Unknown),
+  }),
+);
 
 const nonEmptyString = (value: unknown): value is string =>
   typeof value === "string" && value.trim().length > 0;
 
 const hasIntentDiscoveryMetadata = (metadata: typeof PackageMetadataSchema.Type): boolean => {
   const intent = metadata.intent;
-  if (typeof intent === "object" && intent !== null &&
-    "version" in intent && intent.version === 1 &&
-    "repo" in intent && nonEmptyString(intent.repo) &&
-    "docs" in intent && nonEmptyString(intent.docs)) {
+
+  if (
+    typeof intent === "object" &&
+    intent !== null &&
+    "version" in intent &&
+    intent.version === 1 &&
+    "repo" in intent &&
+    nonEmptyString(intent.repo) &&
+    "docs" in intent &&
+    nonEmptyString(intent.docs)
+  ) {
     return true;
   }
   const repository = metadata.repository;
-  return nonEmptyString(repository) ||
-    (typeof repository === "object" && repository !== null &&
-      "url" in repository && nonEmptyString(repository.url));
+
+  return (
+    nonEmptyString(repository) ||
+    (typeof repository === "object" &&
+      repository !== null &&
+      "url" in repository &&
+      nonEmptyString(repository.url))
+  );
 };
 
 const isSafePackageVersion = (value: string): boolean =>
-  value.length > 0 && value.trim() === value && ![...value].some((character) => {
+  value.length > 0 &&
+  value.trim() === value &&
+  ![...value].some((character) => {
     const code = character.charCodeAt(0);
+
     return code <= 32 || (code >= 127 && code <= 159);
   });
 
 const isContained = (path: Path.Path, root: string, candidate: string): boolean => {
   const relative = path.relative(root, candidate);
+
   return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
 };
 
 const frontmatterScalar = (document: string, key: string): string | undefined => {
   const body = document.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
+
   if (body === undefined) return undefined;
   const lines = body.split(/\r?\n/);
   const index = lines.findIndex((line) => line.startsWith(`${key}:`));
+
   if (index < 0) return undefined;
   const raw = lines[index]?.slice(key.length + 1).trim() ?? "";
   const block = raw.match(/^([|>])(?:[1-9][+-]?|[+-][1-9]?)?$/)?.[1];
+
   if (block !== undefined) {
     const values: Array<string> = [];
+
     for (const line of lines.slice(index + 1)) {
       if (line.length > 0 && !/^\s/.test(line)) break;
       values.push(line.trim());
     }
     const value = block === "|" ? values.join("\n").trim() : values.join(" ").trim();
+
     return value.length > 0 ? value : undefined;
   }
   const quoted = raw.match(/^(['"])([\s\S]*?)\1(?:\s+#.*)?$/)?.[2];
   const value = (quoted ?? raw.replace(/\s+#.*$/, "")).trim();
+
   return value.length > 0 ? value : undefined;
 };
 
-const skillName = (document: string): string | undefined =>
-  frontmatterScalar(document, "name");
+const skillName = (document: string): string | undefined => frontmatterScalar(document, "name");
 
 const skillDescription = (document: string): string | undefined =>
   frontmatterScalar(document, "description");
@@ -92,19 +115,35 @@ const rejectNestedSymlinks = Effect.fn("rejectPackageSkillSymlinks")(function* (
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
   const pending = [skillRoot];
+
   while (pending.length > 0) {
     const current = pending.pop();
+
     if (current === undefined) continue;
     if ((yield* observeSymbolicLink(current)).kind === "symlink") {
-      return yield* new PackageSkillSourceError({ message: `package skill contains a symlink: ${current}` });
+      return yield* new PackageSkillSourceError({
+        message: `package skill contains a symlink: ${current}`,
+      });
     }
-    const info = yield* fs.stat(current).pipe(
-      Effect.mapError(() => new PackageSkillSourceError({ message: `could not inspect package skill: ${current}` })),
-    );
+    const info = yield* fs
+      .stat(current)
+      .pipe(
+        Effect.mapError(
+          () =>
+            new PackageSkillSourceError({ message: `could not inspect package skill: ${current}` }),
+        ),
+      );
+
     if (info.type !== "Directory") continue;
-    for (const entry of yield* fs.readDirectory(current).pipe(
-      Effect.mapError(() => new PackageSkillSourceError({ message: `could not read package skill: ${current}` })),
-    )) pending.push(path.join(current, entry));
+    for (const entry of yield* fs
+      .readDirectory(current)
+      .pipe(
+        Effect.mapError(
+          () =>
+            new PackageSkillSourceError({ message: `could not read package skill: ${current}` }),
+        ),
+      ))
+      pending.push(path.join(current, entry));
   }
 });
 
@@ -124,33 +163,85 @@ const loadInstalledPackageSkills = Effect.fn("loadInstalledPackageSkills")(funct
   const path = yield* Path.Path;
   const packageLink = path.join(projectDir, "node_modules", ...packageName.split("/"));
   const packageRoot = yield* fs.realPath(packageLink).pipe(
-    Effect.mapError(() => new PackageSkillSourceError({ message: `package skill package is not installed: ${packageName}` })),
+    Effect.mapError(
+      () =>
+        new PackageSkillSourceError({
+          message: `package skill package is not installed: ${packageName}`,
+        }),
+    ),
   );
   const packageInfo = yield* fs.stat(packageRoot).pipe(
-    Effect.mapError(() => new PackageSkillSourceError({ message: `could not inspect package skill package: ${packageName}` })),
+    Effect.mapError(
+      () =>
+        new PackageSkillSourceError({
+          message: `could not inspect package skill package: ${packageName}`,
+        }),
+    ),
   );
-  if (packageInfo.type !== "Directory") return yield* new PackageSkillSourceError({ message: `package skill package is not a directory: ${packageName}` });
+
+  if (packageInfo.type !== "Directory")
+    return yield* new PackageSkillSourceError({
+      message: `package skill package is not a directory: ${packageName}`,
+    });
   const metadata = yield* fs.readFileString(path.join(packageRoot, "package.json")).pipe(
     Effect.flatMap(Schema.decodeUnknownEffect(PackageMetadataSchema)),
-    Effect.mapError(() => new PackageSkillSourceError({ message: `invalid package.json for package skill package: ${packageName}` })),
+    Effect.mapError(
+      () =>
+        new PackageSkillSourceError({
+          message: `invalid package.json for package skill package: ${packageName}`,
+        }),
+    ),
   );
-  if (metadata.name !== packageName) return yield* new PackageSkillSourceError({ message: `package.json name does not match package skill package: ${packageName}` });
-  if (!isSafePackageVersion(metadata.version)) return yield* new PackageSkillSourceError({ message: `package.json has an invalid version for package skill package: ${packageName}` });
-  if (!hasIntentDiscoveryMetadata(metadata)) return yield* new PackageSkillSourceError({ message: `package does not declare Intent-compatible discovery metadata: ${packageName}` });
+
+  if (metadata.name !== packageName)
+    return yield* new PackageSkillSourceError({
+      message: `package.json name does not match package skill package: ${packageName}`,
+    });
+  if (!isSafePackageVersion(metadata.version))
+    return yield* new PackageSkillSourceError({
+      message: `package.json has an invalid version for package skill package: ${packageName}`,
+    });
+  if (!hasIntentDiscoveryMetadata(metadata))
+    return yield* new PackageSkillSourceError({
+      message: `package does not declare Intent-compatible discovery metadata: ${packageName}`,
+    });
   const skillsPath = "skills";
   const skillsLink = path.join(packageLink, skillsPath);
-  if ((yield* observeSymbolicLink(skillsLink)).kind === "symlink") return yield* new PackageSkillSourceError({ message: `package skills path is a symlink: ${packageName}/${skillsPath}` });
+
+  if ((yield* observeSymbolicLink(skillsLink)).kind === "symlink")
+    return yield* new PackageSkillSourceError({
+      message: `package skills path is a symlink: ${packageName}/${skillsPath}`,
+    });
   const skillsRoot = yield* fs.realPath(skillsLink).pipe(
-    Effect.mapError(() => new PackageSkillSourceError({ message: `package skill package has no skills directory: ${packageName}` })),
+    Effect.mapError(
+      () =>
+        new PackageSkillSourceError({
+          message: `package skill package has no skills directory: ${packageName}`,
+        }),
+    ),
   );
-  if (!isContained(path, packageRoot, skillsRoot)) return yield* new PackageSkillSourceError({ message: `package skills path resolves outside package root: ${packageName}/${skillsPath}` });
+
+  if (!isContained(path, packageRoot, skillsRoot))
+    return yield* new PackageSkillSourceError({
+      message: `package skills path resolves outside package root: ${packageName}/${skillsPath}`,
+    });
   const skillsInfo = yield* fs.stat(skillsRoot);
-  if (skillsInfo.type !== "Directory") return yield* new PackageSkillSourceError({ message: `package skills path is not a directory: ${packageName}/${skillsPath}` });
+
+  if (skillsInfo.type !== "Directory")
+    return yield* new PackageSkillSourceError({
+      message: `package skills path is not a directory: ${packageName}/${skillsPath}`,
+    });
   const names = (yield* fs.readDirectory(skillsRoot).pipe(
-    Effect.mapError(() => new PackageSkillSourceError({
-      message: `package skill package has no readable skills directory: ${packageName}`,
-    })),
-  )).filter(isSkillName).sort();
+    Effect.mapError(
+      () =>
+        new PackageSkillSourceError({
+          message: `package skill package has no readable skills directory: ${packageName}`,
+        }),
+    ),
+  ))
+    .filter(isSkillName)
+    .sort();
+
   return {
     package: packageName,
     version: metadata.version,
@@ -166,36 +257,57 @@ const inspectPackageSkill = Effect.fn("inspectInstalledPackageSkill")(function*
 ) {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
+
   if (!isSkillName(name)) {
     return yield* new PackageSkillSourceError({ message: `invalid package skill name: ${name}` });
   }
   const selector = `${installed.package}#${name}`;
   const linkPath = path.join(installed.packageLink, "skills", name);
+
   if ((yield* observeSymbolicLink(linkPath)).kind === "symlink") {
-    return yield* new PackageSkillSourceError({ message: `package skill contains a symlink: ${selector}` });
+    return yield* new PackageSkillSourceError({
+      message: `package skill contains a symlink: ${selector}`,
+    });
   }
-  const skillRoot = yield* fs.realPath(linkPath).pipe(
-    Effect.mapError(() => new PackageSkillSourceError({ message: `package skill does not exist: ${selector}` })),
-  );
-  if (!isContained(path, installed.skillsRoot, skillRoot) ||
-    (yield* fs.stat(skillRoot)).type !== "Directory") {
-    return yield* new PackageSkillSourceError({ message: `package skill is not a contained directory: ${selector}` });
+  const skillRoot = yield* fs
+    .realPath(linkPath)
+    .pipe(
+      Effect.mapError(
+        () => new PackageSkillSourceError({ message: `package skill does not exist: ${selector}` }),
+      ),
+    );
+
+  if (
+    !isContained(path, installed.skillsRoot, skillRoot) ||
+    (yield* fs.stat(skillRoot)).type !== "Directory"
+  ) {
+    return yield* new PackageSkillSourceError({
+      message: `package skill is not a contained directory: ${selector}`,
+    });
   }
   yield* rejectNestedSymlinks(skillRoot);
   const document = yield* fs.readFileString(path.join(skillRoot, "SKILL.md")).pipe(
-    Effect.mapError(() => new PackageSkillSourceError({ message: `package skill is missing SKILL.md: ${selector}` })),
+    Effect.mapError(
+      () =>
+        new PackageSkillSourceError({
+          message: `package skill is missing SKILL.md: ${selector}`,
+        }),
+    ),
   );
+
   if (skillName(document) !== name) {
     return yield* new PackageSkillSourceError({
       message: `package skill SKILL.md name must match directory: ${selector}`,
     });
   }
   const description = skillDescription(document);
+
   if (description === undefined) {
     return yield* new PackageSkillSourceError({
       message: `package skill SKILL.md must declare a description: ${selector}`,
     });
   }
+
   return {
     selector,
     name,
@@ -208,41 +320,66 @@ const inspectPackageSkill = Effect.fn("inspectInstalledPackageSkill")(function*
 });
 
 /** Read direct project dependencies only; malformed packages are returned as diagnostics, never executed. */
-export const discoverPackageSkills = Effect.fn("discoverInstalledPackageSkills")(function* (projectDir: string) {
+export const discoverPackageSkills = Effect.fn("discoverInstalledPackageSkills")(function* (
+  projectDir: string,
+) {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
   const candidates: Array<DiscoveredPackageSkill> = [];
   const diagnostics: Array<PackageSkillDiagnostic> = [];
+
   if (!(yield* fs.exists(path.join(projectDir, "package.json")))) {
     return { candidates, diagnostics };
   }
   for (const packageName of yield* readDirectDependencyNames(projectDir)) {
     if (!isTypeScriptPackageName(packageName)) {
-      diagnostics.push({ package: packageName, message: `invalid direct dependency package name: ${packageName}` });
+      diagnostics.push({
+        package: packageName,
+        message: `invalid direct dependency package name: ${packageName}`,
+      });
       continue;
     }
     const skillsLink = path.join(projectDir, "node_modules", ...packageName.split("/"), "skills");
+
     if (!(yield* fs.exists(skillsLink))) continue;
     const installed = yield* Effect.result(loadInstalledPackageSkills(projectDir, packageName));
+
     if (Result.isFailure(installed)) {
       diagnostics.push({ package: packageName, message: installed.failure.message });
       continue;
     }
     for (const name of installed.success.names) {
       const inspected = yield* Effect.result(inspectPackageSkill(installed.success, name));
+
       if (Result.isSuccess(inspected)) candidates.push(inspected.success);
       else diagnostics.push({ package: packageName, message: inspected.failure.message });
     }
   }
-  return { candidates: candidates.sort((left, right) => left.selector.localeCompare(right.selector)), diagnostics };
+
+  return {
+    candidates: candidates.sort((left, right) => left.selector.localeCompare(right.selector)),
+    diagnostics,
+  };
 });
 
 /** Resolve one explicitly selected package skill. Unlike browsing, every malformed or missing part is an error. */
-export const resolvePackageSkillSelector = Effect.fn("resolvePackageSkillSelector")(function* (projectDir: string, selector: string) {
+export const resolvePackageSkillSelector = Effect.fn("resolvePackageSkillSelector")(function* (
+  projectDir: string,
+  selector: string,
+) {
   const parsed = parseSkillSelector(selector);
-  if (parsed?.type !== "package") return yield* new PackageSkillSourceError({ message: `invalid package skill selector: ${selector}` });
+
+  if (parsed?.type !== "package")
+    return yield* new PackageSkillSourceError({
+      message: `invalid package skill selector: ${selector}`,
+    });
   const directDependencies = yield* readDirectDependencyNames(projectDir);
-  if (!directDependencies.includes(parsed.package)) return yield* new PackageSkillSourceError({ message: `package skill package is not a direct dependency: ${parsed.package}` });
+
+  if (!directDependencies.includes(parsed.package))
+    return yield* new PackageSkillSourceError({
+      message: `package skill package is not a direct dependency: ${parsed.package}`,
+    });
+
   return yield* inspectPackageSkill(
     yield* loadInstalledPackageSkills(projectDir, parsed.package),
     parsed.skill,

package/src/path-digest.ts

@@ -2,9 +2,7 @@ import { Crypto, Effect, Encoding, FileSystem, Path, type PlatformError, Schema
 
 import { observeSymbolicLink } from "./node-symbolic-link.ts";
 
-export const DigestSchema = Schema.String.check(
-  Schema.isPattern(/^sha256:[0-9a-f]{64}$/),
-);
+export const DigestSchema = Schema.String.check(Schema.isPattern(/^sha256:[0-9a-f]{64}$/));
 export type Digest = typeof DigestSchema.Type;
 
 export type ObservedPath =
@@ -26,21 +24,30 @@ export class PathInspectionError extends Schema.TaggedErrorClass<PathInspectionE
 
 const textEncoder = new TextEncoder();
 
+// Git preserves only the executable distinction for regular files. Canonicalizing
+// the remaining bits keeps digests stable across checkout and copy umasks.
+const canonicalFileMode = (mode: number): number => ((mode & 0o111) === 0 ? 0o644 : 0o755);
+const rawFileMode = (mode: number): number => mode & 0o777;
+
 const frame = (value: string | Uint8Array): Uint8Array => {
   const bytes = typeof value === "string" ? textEncoder.encode(value) : value;
   const framed = new Uint8Array(4 + bytes.length);
+
   new DataView(framed.buffer).setUint32(0, bytes.length);
   framed.set(bytes, 4);
+
   return framed;
 };
 
 const concatenate = (chunks: ReadonlyArray<Uint8Array>): Uint8Array => {
   const combined = new Uint8Array(chunks.reduce((length, chunk) => length + chunk.length, 0));
   let offset = 0;
+
   for (const chunk of chunks) {
     combined.set(chunk, offset);
     offset += chunk.length;
   }
+
   return combined;
 };
 
@@ -48,10 +55,13 @@ const compareUtf8 = (left: string, right: string): number => {
   const leftBytes = textEncoder.encode(left);
   const rightBytes = textEncoder.encode(right);
   const sharedLength = Math.min(leftBytes.length, rightBytes.length);
+
   for (let index = 0; index < sharedLength; index += 1) {
     const difference = (leftBytes[index] ?? 0) - (rightBytes[index] ?? 0);
+
     if (difference !== 0) return difference;
   }
+
   return leftBytes.length - rightBytes.length;
 };
 
@@ -60,12 +70,18 @@ const digestFrames = Effect.fn("digestPathFrames")(function* (
 ) {
   const crypto = yield* Crypto.Crypto;
   const digest = yield* crypto.digest("SHA-256", concatenate(values.map(frame)));
+
   return `sha256:${Encoding.encodeHex(digest)}`;
 });
 
 const digestFileSystemPath = Effect.fn("digestFileSystemPath")(function* (
   absolutePath: string,
-): Effect.fn.Return<ObservedPath, PlatformError.PlatformError | PathInspectionError, FileSystem.FileSystem | Path.Path | Crypto.Crypto> {
+  fileMode: (mode: number) => number,
+): Effect.fn.Return<
+  ObservedPath,
+  PlatformError.PlatformError | PathInspectionError,
+  FileSystem.FileSystem | Path.Path | Crypto.Crypto
+> {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
   const symbolicLink = yield* observeSymbolicLink(absolutePath);
@@ -78,11 +94,14 @@ const digestFileSystemPath = Effect.fn("digestFileSystemPath")(function* (
     };
   }
 
-  const info = yield* fs.stat(absolutePath).pipe(
-    Effect.catch((error) =>
-      error.reason._tag === "NotFound" ? Effect.void : Effect.fail(error),
-    ),
-  );
+  const info = yield* fs
+    .stat(absolutePath)
+    .pipe(
+      Effect.catch((error) =>
+        error.reason._tag === "NotFound" ? Effect.void : Effect.fail(error),
+      ),
+    );
+
   if (info === undefined) return { kind: "missing" };
 
   if (info.type === "File") {
@@ -90,7 +109,7 @@ const digestFileSystemPath = Effect.fn("digestFileSystemPath")(function* (
       kind: "file",
       digest: yield* digestFrames([
         "file-v1",
-        String(info.mode & 0o777),
+        String(fileMode(info.mode)),
         yield* fs.readFile(absolutePath),
       ]),
     };
@@ -99,9 +118,11 @@ const digestFileSystemPath = Effect.fn("digestFileSystemPath")(function* (
   if (info.type === "Directory") {
     const entries = (yield* fs.readDirectory(absolutePath)).sort(compareUtf8);
     const frames: Array<string | Uint8Array> = ["directory-v1"];
+
     for (const entry of entries) {
       const childPath = path.join(absolutePath, entry);
-      const child = yield* digestFileSystemPath(childPath);
+      const child = yield* digestFileSystemPath(childPath, fileMode);
+
       if (child.kind === "missing") {
         return yield* new PathInspectionError({
           path: childPath,
@@ -111,6 +132,7 @@ const digestFileSystemPath = Effect.fn("digestFileSystemPath")(function* (
       }
       frames.push(entry, child.kind, child.digest);
     }
+
     return { kind: "directory", digest: yield* digestFrames(frames) };
   }
 
@@ -122,7 +144,19 @@ const digestFileSystemPath = Effect.fn("digestFileSystemPath")(function* (
 });
 
 export const observePath = Effect.fn("observeManagedPath")(function* (absolutePath: string) {
-  return yield* digestFileSystemPath(absolutePath).pipe(
+  return yield* digestFileSystemPath(absolutePath, canonicalFileMode).pipe(
+    Effect.mapError((cause) =>
+      cause instanceof PathInspectionError
+        ? cause
+        : new PathInspectionError({ path: absolutePath, operation: "inspect", cause }),
+    ),
+  );
+});
+
+export const observePathWithRawModes = Effect.fn("observeManagedPathWithRawModes")(function* (
+  absolutePath: string,
+) {
+  return yield* digestFileSystemPath(absolutePath, rawFileMode).pipe(
     Effect.mapError((cause) =>
       cause instanceof PathInspectionError
         ? cause
@@ -139,7 +173,7 @@ export const digestFileContent = Effect.fn("digestFileContent")(function* (
   value: string,
   mode = 0o644,
 ) {
-  return yield* digestFrames(["file-v1", String(mode), value]);
+  return yield* digestFrames(["file-v1", String(canonicalFileMode(mode)), value]);
 });
 
 export const digestSymlinkTarget = Effect.fn("digestSymlinkTarget")(function* (target: string) {