meno-core 1.0.53 → 1.1.0

package/lib/shared/paths/PathUtils.ts

@@ -32,14 +32,14 @@ import { isSlotMarker } from '../nodeUtils';
 function calculateChildrenExpansionOffset(
   componentPath: Path,
   componentStructure: ComponentNode | undefined,
-  instanceChildren: ComponentNode['children'] | undefined
+  instanceChildren: ComponentNode['children'] | undefined,
 ): number {
   if (!componentStructure || !Array.isArray(instanceChildren)) {
     return 0;
   }
 
   // Count actual children (accounting for marker expansion)
-  const childrenCount = Array.isArray(instanceChildren) ? instanceChildren.length : (instanceChildren ? 1 : 0);
+  const childrenCount = Array.isArray(instanceChildren) ? instanceChildren.length : instanceChildren ? 1 : 0;
 
   let offset = 0;
   let currentNode = componentStructure;
@@ -47,6 +47,7 @@ function calculateChildrenExpansionOffset(
   // Walk the component structure following the path
   for (let i = 1; i < componentPath.length; i++) {
     const index = componentPath[i];
+    if (index === undefined) break;
 
     // Get children of current node
     if (!currentNode || !Array.isArray((currentNode as any).children)) {
@@ -72,7 +73,7 @@ function calculateChildrenExpansionOffset(
 
     // Move to next node in the path
     if (index < children.length) {
-      currentNode = (children[index] as any) as ComponentNode;
+      currentNode = children[index] as any as ComponentNode;
     } else {
       break;
     }
@@ -128,12 +129,12 @@ export function buildParentPaths(path: Path): Path[] {
   if (isRootPath(path)) {
     return [];
   }
-  
+
   const parents: Path[] = [];
   for (let i = 1; i < path.length; i++) {
     parents.push(path.slice(0, i));
   }
-  
+
   return parents;
 }
 
@@ -186,12 +187,12 @@ export function convertPagePathToComponentPath(
   pagePath: Path,
   componentInstancePath: Path,
   componentStructure?: ComponentNode,
-  instanceChildren?: ComponentNode['children']
+  instanceChildren?: ComponentNode['children'],
 ): Path | null {
   // Check if pagePath starts with componentInstancePath
   // Path must be within or equal to component instance
-  const isWithinComponent = isAncestorPath(componentInstancePath, pagePath) ||
-                             pathsEqual(pagePath, componentInstancePath);
+  const isWithinComponent =
+    isAncestorPath(componentInstancePath, pagePath) || pathsEqual(pagePath, componentInstancePath);
 
   if (!isWithinComponent) {
     return null; // Path is not within the component instance
@@ -212,7 +213,7 @@ export function convertPagePathToComponentPath(
       isSlotMarker(componentStructure.children[0])
     ) {
       // Children marker is at index 0, so indices 0 to (childrenCount - 1) map to children
-      const pageFirstIndex = suffix[0];
+      const pageFirstIndex = suffix[0] ?? 0;
 
       // If page index is within the children range, it's a child (no component path)
       if (pageFirstIndex < childrenCount) {
@@ -224,7 +225,7 @@ export function convertPagePathToComponentPath(
         // Page index is after slot expansion
         // Subtract the offset (childrenCount - 1) to get component index
         const offset = childrenCount - 1;
-        adjustedSuffix = [suffix[0] - offset, ...suffix.slice(1)];
+        adjustedSuffix = [pageFirstIndex - offset, ...suffix.slice(1)];
       }
     }
   }
@@ -264,7 +265,7 @@ export function convertComponentPathToPagePath(
   componentPath: Path,
   componentInstancePath: Path,
   componentStructure?: ComponentNode,
-  instanceChildren?: ComponentNode['children']
+  instanceChildren?: ComponentNode['children'],
 ): Path {
   // Component paths start with [0] (component root)
   if (componentPath.length === 1 && componentPath[0] === 0) {
@@ -281,10 +282,9 @@ export function convertComponentPathToPagePath(
   // Apply offset to first level index if slot expansion occurred
   let adjustedSuffix = suffix;
   if (offset > 0 && suffix.length > 0) {
-    adjustedSuffix = [suffix[0] + offset, ...suffix.slice(1)];
+    adjustedSuffix = [(suffix[0] ?? 0) + offset, ...suffix.slice(1)];
   }
 
   // Append adjusted suffix to component instance path
   return [...componentInstancePath, ...adjustedSuffix];
 }
-

package/lib/shared/paths/PathValidator.test.ts

@@ -1,10 +1,5 @@
 import { describe, test, expect } from 'bun:test';
-import {
-  validatePath,
-  isRootPath,
-  InvalidPathError,
-  PathConversionError
-} from './PathValidator';
+import { validatePath, isRootPath, InvalidPathError, PathConversionError } from './PathValidator';
 
 describe('PathValidator', () => {
   describe('validatePath', () => {
@@ -175,15 +170,7 @@ describe('PathValidator', () => {
     });
 
     test('stores any input type', () => {
-      const inputs = [
-        'string',
-        123,
-        null,
-        undefined,
-        {},
-        [],
-        true
-      ];
+      const inputs = ['string', 123, null, undefined, {}, [], true];
       for (const input of inputs) {
         const error = new PathConversionError('Test', input);
         expect(error.input).toBe(input);

package/lib/shared/paths/PathValidator.ts

@@ -9,14 +9,21 @@ import type { Path } from './Path';
  * Custom error classes for path operations
  */
 export class InvalidPathError extends Error {
-  constructor(message: string, public readonly path: unknown, public readonly index?: number) {
+  constructor(
+    message: string,
+    public readonly path: unknown,
+    public readonly index?: number,
+  ) {
     super(message);
     this.name = 'InvalidPathError';
   }
 }
 
 export class PathConversionError extends Error {
-  constructor(message: string, public readonly input: unknown) {
+  constructor(
+    message: string,
+    public readonly input: unknown,
+  ) {
     super(message);
     this.name = 'PathConversionError';
   }
@@ -30,15 +37,11 @@ export function validatePath(path: Path): void {
   if (!Array.isArray(path)) {
     throw new InvalidPathError('Path must be an array', path);
   }
-  
+
   for (let i = 0; i < path.length; i++) {
     const value = path[i];
-    if (typeof value !== 'number' || isNaN(value) || !isFinite(value)) {
-      throw new InvalidPathError(
-        `Invalid path value at index ${i}: expected number, got ${typeof value}`,
-        path,
-        i
-      );
+    if (typeof value !== 'number' || Number.isNaN(value) || !Number.isFinite(value)) {
+      throw new InvalidPathError(`Invalid path value at index ${i}: expected number, got ${typeof value}`, path, i);
     }
   }
 }
@@ -50,4 +53,3 @@ export function validatePath(path: Path): void {
 export function isRootPath(path: Path): boolean {
   return path.length === 0 || (path.length === 1 && path[0] === 0);
 }
-

package/lib/shared/paths/index.ts

@@ -1,7 +1,7 @@
 /**
  * Path Utilities
  * Unified path handling system
- * 
+ *
  * This module provides a single source of truth for path operations.
  * All path-related functionality is consolidated here.
  */
@@ -45,4 +45,3 @@ export {
   convertPagePathToComponentPath,
   convertComponentPathToPagePath,
 } from './PathUtils';
-

package/lib/shared/permissions.test.ts

@@ -0,0 +1,168 @@
+import { describe, test, expect } from 'bun:test';
+import { resolvePermissions, canEdit, matchesPermissionPattern, matchesAnyPermissionPattern } from './permissions';
+import type { PermissionsPolicy, ResourceRef } from './types/permissions';
+
+const page = (id: string): ResourceRef => ({ kind: 'page', id });
+const component = (id: string): ResourceRef => ({ kind: 'component', id });
+const cms = (id: string): ResourceRef => ({ kind: 'cms', id });
+const config = (id: string): ResourceRef => ({ kind: 'config', id });
+
+describe('matchesPermissionPattern', () => {
+  test('exact match', () => {
+    expect(matchesPermissionPattern('about', 'about')).toBe(true);
+    expect(matchesPermissionPattern('about', 'contact')).toBe(false);
+  });
+
+  test('bare "*" matches anything', () => {
+    expect(matchesPermissionPattern('*', 'anything')).toBe(true);
+    expect(matchesPermissionPattern('*', '')).toBe(true);
+  });
+
+  test('"blog/*" matches under the prefix, including deeper paths (wildcard crosses "/")', () => {
+    expect(matchesPermissionPattern('blog/*', 'blog/post')).toBe(true);
+    expect(matchesPermissionPattern('blog/*', 'blog/2026/post')).toBe(true);
+    expect(matchesPermissionPattern('blog/*', 'marketing/post')).toBe(false);
+  });
+
+  test('"*Hero" suffix match', () => {
+    expect(matchesPermissionPattern('*Hero', 'HomeHero')).toBe(true);
+    expect(matchesPermissionPattern('*Hero', 'HeroBanner')).toBe(false);
+  });
+
+  test('regex special chars in the pattern are treated literally', () => {
+    expect(matchesPermissionPattern('a.b', 'a.b')).toBe(true);
+    expect(matchesPermissionPattern('a.b', 'axb')).toBe(false);
+  });
+
+  test('matchesAnyPermissionPattern handles undefined / empty lists', () => {
+    expect(matchesAnyPermissionPattern(undefined, 'x')).toBe(false);
+    expect(matchesAnyPermissionPattern([], 'x')).toBe(false);
+    expect(matchesAnyPermissionPattern(['a', 'b*'], 'bar')).toBe(true);
+  });
+});
+
+describe('resolvePermissions — no policy (unmanaged project)', () => {
+  test('everyone is admin and can edit everything', () => {
+    const r = resolvePermissions(null, { login: 'alice' });
+    expect(r.isAdmin).toBe(true);
+    expect(r.role).toBe('admin');
+    expect(canEdit(r, page('anything'))).toBe(true);
+    expect(canEdit(r, config('colors'))).toBe(true);
+  });
+
+  test('canManagePolicy: repo admins and local/unauthenticated runs only', () => {
+    expect(resolvePermissions(null, { login: 'bob' }).canManagePolicy).toBe(false);
+    expect(resolvePermissions(null, { login: 'bob', isRepoAdmin: true }).canManagePolicy).toBe(true);
+    expect(resolvePermissions(null, { login: null }).canManagePolicy).toBe(true);
+  });
+});
+
+describe('resolvePermissions — present policy', () => {
+  const policy: PermissionsPolicy = {
+    version: 1,
+    defaultRole: 'viewer',
+    members: {
+      alice: { allow: { cms: ['posts'], pages: ['blog/*'] } },
+      Bob: { allow: { pages: ['marketing/*'], components: ['*'] } },
+      carol: { role: 'admin' },
+      dave: { role: 'viewer' },
+    },
+    teams: {
+      content: { allow: { cms: ['*'] } },
+      leads: { role: 'admin' },
+    },
+  };
+
+  test('unlisted authenticated user gets defaultRole (viewer → edits nothing)', () => {
+    const r = resolvePermissions(policy, { login: 'stranger' });
+    expect(r.role).toBe('viewer');
+    expect(r.isAdmin).toBe(false);
+    expect(canEdit(r, page('blog/post'))).toBe(false);
+  });
+
+  test('editor edits only allow-listed resources', () => {
+    const r = resolvePermissions(policy, { login: 'alice' });
+    expect(r.role).toBe('editor');
+    expect(canEdit(r, page('blog/post'))).toBe(true);
+    expect(canEdit(r, page('marketing/home'))).toBe(false);
+    expect(canEdit(r, cms('posts'))).toBe(true);
+    expect(canEdit(r, cms('products'))).toBe(false);
+    expect(canEdit(r, component('Card'))).toBe(false);
+    expect(canEdit(r, config('colors'))).toBe(false);
+  });
+
+  test('login lookup is case-insensitive', () => {
+    const r = resolvePermissions(policy, { login: 'BOB' });
+    expect(r.role).toBe('editor');
+    expect(canEdit(r, page('marketing/home'))).toBe(true);
+    expect(canEdit(r, component('AnythingGoes'))).toBe(true);
+  });
+
+  test('explicit admin role edits everything regardless of allow-lists', () => {
+    const r = resolvePermissions(policy, { login: 'carol' });
+    expect(r.isAdmin).toBe(true);
+    expect(r.canManagePolicy).toBe(true);
+    expect(canEdit(r, page('anything'))).toBe(true);
+    expect(canEdit(r, config('variables'))).toBe(true);
+  });
+
+  test('explicit viewer role edits nothing', () => {
+    const r = resolvePermissions(policy, { login: 'dave' });
+    expect(r.role).toBe('viewer');
+    expect(canEdit(r, page('anything'))).toBe(false);
+    expect(r.canManagePolicy).toBe(false);
+  });
+
+  test('repo admin is always admin, even when the policy lists them lower', () => {
+    const r = resolvePermissions(policy, { login: 'dave', isRepoAdmin: true });
+    expect(r.isAdmin).toBe(true);
+    expect(r.role).toBe('admin');
+    expect(canEdit(r, page('anything'))).toBe(true);
+    expect(r.canManagePolicy).toBe(true);
+  });
+
+  test('team grants apply and unite with member grants', () => {
+    const r = resolvePermissions(policy, { login: 'alice', teams: ['content'] });
+    expect(r.role).toBe('editor');
+    // member grant (blog) + team grant (all cms)
+    expect(canEdit(r, page('blog/post'))).toBe(true);
+    expect(canEdit(r, cms('products'))).toBe(true);
+  });
+
+  test('highest role across member + teams wins (team admin promotes)', () => {
+    const r = resolvePermissions(policy, { login: 'alice', teams: ['leads'] });
+    expect(r.isAdmin).toBe(true);
+    expect(canEdit(r, config('project'))).toBe(true);
+  });
+
+  test('team lookup is case-insensitive', () => {
+    const r = resolvePermissions(policy, { login: 'nobody', teams: ['Content'] });
+    expect(canEdit(r, cms('posts'))).toBe(true);
+  });
+
+  test('config area allow-lists support wildcards', () => {
+    const p: PermissionsPolicy = {
+      version: 1,
+      members: { ed: { allow: { config: ['colors', 'variables'] } }, all: { allow: { config: ['*'] } } },
+    };
+    const ed = resolvePermissions(p, { login: 'ed' });
+    expect(canEdit(ed, config('colors'))).toBe(true);
+    expect(canEdit(ed, config('i18n'))).toBe(false);
+    const all = resolvePermissions(p, { login: 'all' });
+    expect(canEdit(all, config('i18n'))).toBe(true);
+  });
+
+  test('defaultRole can widen the baseline (editor default)', () => {
+    const p: PermissionsPolicy = { version: 1, defaultRole: 'editor', members: { ed: { allow: { pages: ['x'] } } } };
+    // An unlisted user is an editor with NO allow-list → edits nothing.
+    const unlisted = resolvePermissions(p, { login: 'stranger' });
+    expect(unlisted.role).toBe('editor');
+    expect(canEdit(unlisted, page('x'))).toBe(false);
+  });
+
+  test('null login with a present policy falls to defaultRole', () => {
+    const r = resolvePermissions(policy, { login: null });
+    expect(r.role).toBe('viewer');
+    expect(canEdit(r, page('blog/post'))).toBe(false);
+  });
+});

package/lib/shared/permissions.ts

@@ -0,0 +1,162 @@
+/**
+ * Permission resolver
+ *
+ * Pure functions that turn a {@link PermissionsPolicy} + a
+ * {@link PermissionIdentity} into a queryable {@link ResolvedPermissions}, and
+ * answer "can this identity edit this resource?". No IO — the policy is loaded
+ * and the identity gathered by the caller. Shared by the studio client (UI
+ * gating) and any future server-side mirror.
+ *
+ * See `./types/permissions.ts` for the data model and the SOFT-enforcement
+ * caveat.
+ */
+
+import type {
+  PermissionGrant,
+  PermissionIdentity,
+  PermissionRole,
+  PermissionRule,
+  PermissionsPolicy,
+  ResolvedPermissions,
+  ResourceKind,
+  ResourceRef,
+} from './types/permissions';
+
+/** Role capability ordering, low → high. */
+const ROLE_RANK: Record<PermissionRole, number> = { viewer: 0, editor: 1, admin: 2 };
+
+/** Maps a {@link ResourceKind} to its {@link PermissionRule} key. */
+const RULE_KEY: Record<ResourceKind, keyof PermissionRule> = {
+  page: 'pages',
+  component: 'components',
+  cms: 'cms',
+  config: 'config',
+};
+
+/** The empty (all-kinds-present) allow rule used as a merge seed. */
+function emptyAllow(): Required<PermissionRule> {
+  return { pages: [], components: [], cms: [], config: [] };
+}
+
+function higherRole(a: PermissionRole, b: PermissionRole): PermissionRole {
+  return ROLE_RANK[b] > ROLE_RANK[a] ? b : a;
+}
+
+/** A grant's role: explicit, else `editor` when it carries an allow-list, else `viewer`. */
+function grantRole(grant: PermissionGrant): PermissionRole {
+  if (grant.role) return grant.role;
+  return grant.allow ? 'editor' : 'viewer';
+}
+
+function mergeAllow(grants: PermissionGrant[]): Required<PermissionRule> {
+  const merged = emptyAllow();
+  for (const grant of grants) {
+    const allow = grant.allow;
+    if (!allow) continue;
+    for (const kind of Object.keys(merged) as (keyof PermissionRule)[]) {
+      const patterns = allow[kind];
+      if (patterns) merged[kind].push(...patterns);
+    }
+  }
+  // Dedupe each list while preserving order.
+  for (const kind of Object.keys(merged) as (keyof PermissionRule)[]) {
+    merged[kind] = [...new Set(merged[kind])];
+  }
+  return merged;
+}
+
+const REGEX_SPECIALS = /[.+?^${}()|[\]\\]/g;
+
+/**
+ * Glob match for a single permission pattern against a value. `*` matches any
+ * run of characters (including `/`); every other character is literal. An exact
+ * (wildcard-free) pattern must equal the value.
+ */
+export function matchesPermissionPattern(pattern: string, value: string): boolean {
+  if (pattern === value) return true;
+  if (!pattern.includes('*')) return false;
+  const source = pattern
+    .split('*')
+    .map((segment) => segment.replace(REGEX_SPECIALS, '\\$&'))
+    .join('.*');
+  return new RegExp(`^${source}$`).test(value);
+}
+
+/** True if `value` matches any pattern in `patterns`. */
+export function matchesAnyPermissionPattern(patterns: string[] | undefined, value: string): boolean {
+  return !!patterns && patterns.some((pattern) => matchesPermissionPattern(pattern, value));
+}
+
+/**
+ * Resolve a policy + identity into a capability set.
+ *
+ * - `policy == null` → an UNMANAGED project: everyone edits everything (status
+ *   quo). `canManagePolicy` (who may create the first policy) is gated to repo
+ *   admins, or anyone on a local/unauthenticated run.
+ * - With a policy present, an identity not listed in `members`/`teams` gets
+ *   `defaultRole` (default `viewer`). `login: null` is treated the same way —
+ *   callers that want to bypass gating for local runs should skip resolution
+ *   rather than pass a null login.
+ * - A GitHub repo admin (`identity.isRepoAdmin`) is ALWAYS an admin here,
+ *   regardless of the policy (bootstrap safety against lockout).
+ */
+export function resolvePermissions(
+  policy: PermissionsPolicy | null | undefined,
+  identity: PermissionIdentity,
+): ResolvedPermissions {
+  const login = identity.login ?? null;
+  const isRepoAdmin = identity.isRepoAdmin === true;
+
+  if (!policy) {
+    return {
+      login,
+      role: 'admin',
+      isAdmin: true,
+      canManagePolicy: login == null || isRepoAdmin,
+      allow: emptyAllow(),
+    };
+  }
+
+  const grants: PermissionGrant[] = [];
+
+  const lookupLogin = login?.toLowerCase() ?? null;
+  if (lookupLogin && policy.members) {
+    for (const [key, grant] of Object.entries(policy.members)) {
+      if (key.toLowerCase() === lookupLogin) grants.push(grant);
+    }
+  }
+
+  if (policy.teams && identity.teams && identity.teams.length > 0) {
+    const teamSet = new Set(identity.teams.map((team) => team.toLowerCase()));
+    for (const [key, grant] of Object.entries(policy.teams)) {
+      if (teamSet.has(key.toLowerCase())) grants.push(grant);
+    }
+  }
+
+  const defaultRole: PermissionRole = policy.defaultRole ?? 'viewer';
+  const baseRole =
+    grants.length === 0
+      ? defaultRole
+      : grants.reduce<PermissionRole>((acc, g) => higherRole(acc, grantRole(g)), 'viewer');
+
+  const isAdmin = isRepoAdmin || baseRole === 'admin';
+
+  return {
+    login,
+    role: isAdmin ? 'admin' : baseRole,
+    isAdmin,
+    canManagePolicy: isAdmin,
+    allow: mergeAllow(grants),
+  };
+}
+
+/**
+ * May this identity edit this resource? Admins edit everything; viewers edit
+ * nothing; editors edit only resources whose id matches the merged allow-list
+ * for the resource's kind.
+ */
+export function canEdit(resolved: ResolvedPermissions, ref: ResourceRef): boolean {
+  if (resolved.isAdmin) return true;
+  if (resolved.role === 'viewer') return false;
+  return matchesAnyPermissionPattern(resolved.allow[RULE_KEY[ref.kind]], ref.id);
+}