@hamak/shared-utils 0.9.0 → 0.9.1

package/dist/core-utils-filesystem.d.ts

@@ -12,6 +12,44 @@ export interface FileMemoState {
     originalContent: Holder;
     modified: boolean;
 }
+/**
+ * Client-side, UI-facing capabilities for a filesystem node.
+ *
+ * All fields optional — a provider specifies only what it needs (e.g.
+ * `{ write: false }`); the rest fall back to their defaults via
+ * {@link resolveNodePermissions} / {@link resolvePermissions}. When
+ * `state.permissions` is entirely absent the node is fully permissive (rwx),
+ * so existing nodes behave exactly as before.
+ *
+ * NOTE: this is NOT a security boundary. It mirrors the source's real ACL so
+ * the UI can reflect what's allowed without a round-trip; server-side
+ * authorization still enforces for real.
+ */
+export interface FileSystemNodePermissions {
+    /** May the content be read/loaded. Default: true. */
+    read?: boolean;
+    /** May the content be edited (updateFileContent / setFileContent !fromRemote). Default: true. */
+    write?: boolean;
+    /** May the node be removed. Default: = write. */
+    remove?: boolean;
+    /** May the node be renamed / moved. Default: = write. */
+    rename?: boolean;
+    /** (directories) may children be created. Default: = write. */
+    createChildren?: boolean;
+    /** Human-facing reason surfaced in the UI ("Computed listing — read-only"). */
+    reason?: string;
+}
+/**
+ * Fully-resolved permissions: every capability decided, `reason` optional.
+ */
+export interface ResolvedFileSystemNodePermissions {
+    read: boolean;
+    write: boolean;
+    remove: boolean;
+    rename: boolean;
+    createChildren: boolean;
+    reason?: string;
+}
 export interface FileSystemNodeState {
     contentLoaded: boolean;
     contentLoading: boolean;
@@ -20,10 +58,31 @@ export interface FileSystemNodeState {
         message?: string;
     };
     memo?: FileMemoState;
+    /** Client-side capabilities. Absent = fully permissive (rwx). */
+    permissions?: FileSystemNodePermissions;
     contentHistory: any[];
     extensionStates: Record<string, unknown>;
 }
 export declare function fileSystemNodeInitialState(contentPresent?: boolean): FileSystemNodeState;
+/**
+ * Fold a partial permissions object into fully-resolved capabilities, applying
+ * defaults: `read`/`write` default true, and `remove`/`rename`/`createChildren`
+ * default to the resolved `write` value. Node-local (no inheritance).
+ */
+export declare function resolveNodePermissions(perms?: FileSystemNodePermissions): ResolvedFileSystemNodePermissions;
+/**
+ * Resolve permissions for a node at `path` with directory inheritance.
+ *
+ * Walks root → target, folding each ancestor's explicitly-set capabilities;
+ * a child overrides its ancestors per-field (a read-only directory therefore
+ * makes descendants read-only unless a child sets `write: true`). Undefined
+ * fields fall through to defaults (see {@link resolveNodePermissions}).
+ */
+export declare function resolvePermissions(root: FileSystemNode | undefined, path: Path): ResolvedFileSystemNodePermissions;
+/** Node-local writability (no inheritance). Absent permissions ⇒ writable. */
+export declare function isWritable(node: FileSystemNode | undefined): boolean;
+/** Node-local read-only check (no inheritance). Inverse of {@link isWritable}. */
+export declare function isReadOnly(node: FileSystemNode | undefined): boolean;
 export interface FileSystemNodeBase {
     type: 'directory' | 'file';
     name: string;

package/dist/core-utils-filesystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core-utils-filesystem.d.ts","sourceRoot":"","sources":["../src/core-utils-filesystem.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"core-utils-filesystem.d.ts","sourceRoot":"","sources":["../src/core-utils-filesystem.ts"],"names":[],"mappings":"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"}

package/dist/core-utils-filesystem.js

@@ -8,6 +8,60 @@ export function fileSystemNodeInitialState(contentPresent = true) {
         extensionStates: {}
     };
 }
+/**
+ * Fold a partial permissions object into fully-resolved capabilities, applying
+ * defaults: `read`/`write` default true, and `remove`/`rename`/`createChildren`
+ * default to the resolved `write` value. Node-local (no inheritance).
+ */
+export function resolveNodePermissions(perms) {
+    const read = perms?.read ?? true;
+    const write = perms?.write ?? true;
+    return {
+        read,
+        write,
+        remove: perms?.remove ?? write,
+        rename: perms?.rename ?? write,
+        createChildren: perms?.createChildren ?? write,
+        reason: perms?.reason
+    };
+}
+/**
+ * Resolve permissions for a node at `path` with directory inheritance.
+ *
+ * Walks root → target, folding each ancestor's explicitly-set capabilities;
+ * a child overrides its ancestors per-field (a read-only directory therefore
+ * makes descendants read-only unless a child sets `write: true`). Undefined
+ * fields fall through to defaults (see {@link resolveNodePermissions}).
+ */
+export function resolvePermissions(root, path) {
+    const merged = {};
+    let current = root;
+    const segments = Pathway.of(path).getSegments();
+    for (let i = 0;; i++) {
+        const perms = current?.state?.permissions;
+        if (perms) {
+            // Later (deeper) nodes override earlier ones, per defined field only.
+            for (const key of Object.keys(perms)) {
+                if (perms[key] !== undefined) {
+                    merged[key] = perms[key];
+                }
+            }
+        }
+        if (i >= segments.length || current === undefined || current.type !== 'directory') {
+            break;
+        }
+        current = current.children[segments[i]];
+    }
+    return resolveNodePermissions(merged);
+}
+/** Node-local writability (no inheritance). Absent permissions ⇒ writable. */
+export function isWritable(node) {
+    return resolveNodePermissions(node?.state?.permissions).write;
+}
+/** Node-local read-only check (no inheritance). Inverse of {@link isWritable}. */
+export function isReadOnly(node) {
+    return !isWritable(node);
+}
 function isRoot(node) {
     switch (node.type) {
         case "directory": {

package/dist/es2015/core-utils-filesystem.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fsutils = exports.DirectoryNodePathwayResolver = exports.fileSystemNodeInitialState = void 0;
+exports.fsutils = exports.DirectoryNodePathwayResolver = exports.isReadOnly = exports.isWritable = exports.resolvePermissions = exports.resolveNodePermissions = exports.fileSystemNodeInitialState = void 0;
 const core_utils_pathway_1 = require("./core-utils-pathway");
 function fileSystemNodeInitialState(contentPresent = true) {
     return {
@@ -12,6 +12,67 @@ function fileSystemNodeInitialState(contentPresent = true) {
     };
 }
 exports.fileSystemNodeInitialState = fileSystemNodeInitialState;
+/**
+ * Fold a partial permissions object into fully-resolved capabilities, applying
+ * defaults: `read`/`write` default true, and `remove`/`rename`/`createChildren`
+ * default to the resolved `write` value. Node-local (no inheritance).
+ */
+function resolveNodePermissions(perms) {
+    var _a, _b, _c, _d, _e;
+    const read = (_a = perms === null || perms === void 0 ? void 0 : perms.read) !== null && _a !== void 0 ? _a : true;
+    const write = (_b = perms === null || perms === void 0 ? void 0 : perms.write) !== null && _b !== void 0 ? _b : true;
+    return {
+        read,
+        write,
+        remove: (_c = perms === null || perms === void 0 ? void 0 : perms.remove) !== null && _c !== void 0 ? _c : write,
+        rename: (_d = perms === null || perms === void 0 ? void 0 : perms.rename) !== null && _d !== void 0 ? _d : write,
+        createChildren: (_e = perms === null || perms === void 0 ? void 0 : perms.createChildren) !== null && _e !== void 0 ? _e : write,
+        reason: perms === null || perms === void 0 ? void 0 : perms.reason
+    };
+}
+exports.resolveNodePermissions = resolveNodePermissions;
+/**
+ * Resolve permissions for a node at `path` with directory inheritance.
+ *
+ * Walks root → target, folding each ancestor's explicitly-set capabilities;
+ * a child overrides its ancestors per-field (a read-only directory therefore
+ * makes descendants read-only unless a child sets `write: true`). Undefined
+ * fields fall through to defaults (see {@link resolveNodePermissions}).
+ */
+function resolvePermissions(root, path) {
+    var _a;
+    const merged = {};
+    let current = root;
+    const segments = core_utils_pathway_1.Pathway.of(path).getSegments();
+    for (let i = 0;; i++) {
+        const perms = (_a = current === null || current === void 0 ? void 0 : current.state) === null || _a === void 0 ? void 0 : _a.permissions;
+        if (perms) {
+            // Later (deeper) nodes override earlier ones, per defined field only.
+            for (const key of Object.keys(perms)) {
+                if (perms[key] !== undefined) {
+                    merged[key] = perms[key];
+                }
+            }
+        }
+        if (i >= segments.length || current === undefined || current.type !== 'directory') {
+            break;
+        }
+        current = current.children[segments[i]];
+    }
+    return resolveNodePermissions(merged);
+}
+exports.resolvePermissions = resolvePermissions;
+/** Node-local writability (no inheritance). Absent permissions ⇒ writable. */
+function isWritable(node) {
+    var _a;
+    return resolveNodePermissions((_a = node === null || node === void 0 ? void 0 : node.state) === null || _a === void 0 ? void 0 : _a.permissions).write;
+}
+exports.isWritable = isWritable;
+/** Node-local read-only check (no inheritance). Inverse of {@link isWritable}. */
+function isReadOnly(node) {
+    return !isWritable(node);
+}
+exports.isReadOnly = isReadOnly;
 function isRoot(node) {
     switch (node.type) {
         case "directory": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hamak/shared-utils",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "private": false,
   "type": "module",
   "description": "Shared utilities for path navigation, filesystem operations, and common helpers",