apcore-js 0.5.0 → 0.6.0

package/planning/acl-system/state.json

@@ -1,76 +0,0 @@
-{
-  "feature": "acl-system",
-  "created": "2026-02-16T00:00:00Z",
-  "updated": "2026-02-16T00:00:00Z",
-  "status": "completed",
-  "execution_order": [
-    "acl-rule",
-    "pattern-matching",
-    "conditional-rules",
-    "acl-core",
-    "yaml-loading"
-  ],
-  "progress": {
-    "total_tasks": 5,
-    "completed": 5,
-    "in_progress": 0,
-    "pending": 0
-  },
-  "tasks": [
-    {
-      "id": "acl-rule",
-      "file": "tasks/acl-rule.md",
-      "title": "ACLRule Interface Definition",
-      "status": "completed",
-      "started_at": "2026-02-16T08:00:00Z",
-      "completed_at": "2026-02-16T08:45:00Z",
-      "assignee": null,
-      "commits": []
-    },
-    {
-      "id": "pattern-matching",
-      "file": "tasks/pattern-matching.md",
-      "title": "matchPattern() Wildcard Matching (Algorithm A08)",
-      "status": "completed",
-      "started_at": "2026-02-16T08:45:00Z",
-      "completed_at": "2026-02-16T10:15:00Z",
-      "assignee": null,
-      "commits": []
-    },
-    {
-      "id": "conditional-rules",
-      "file": "tasks/conditional-rules.md",
-      "title": "Conditional Rule Evaluation (identity_types, roles, max_call_depth)",
-      "status": "completed",
-      "started_at": "2026-02-16T10:15:00Z",
-      "completed_at": "2026-02-16T11:45:00Z",
-      "assignee": null,
-      "commits": []
-    },
-    {
-      "id": "acl-core",
-      "file": "tasks/acl-core.md",
-      "title": "ACL Class with check(), addRule(), removeRule()",
-      "status": "completed",
-      "started_at": "2026-02-16T11:45:00Z",
-      "completed_at": "2026-02-16T14:00:00Z",
-      "assignee": null,
-      "commits": []
-    },
-    {
-      "id": "yaml-loading",
-      "file": "tasks/yaml-loading.md",
-      "title": "ACL.load() from YAML and reload() Support",
-      "status": "completed",
-      "started_at": "2026-02-16T14:00:00Z",
-      "completed_at": "2026-02-16T15:30:00Z",
-      "assignee": null,
-      "commits": []
-    }
-  ],
-  "metadata": {
-    "source_doc": "planning/features/acl-system.md",
-    "created_by": "code-forge",
-    "version": "1.0"
-  }
-}

package/planning/acl-system/tasks/acl-core.md

@@ -1,226 +0,0 @@
-# Task: ACL Class with check(), addRule(), removeRule()
-
-## Goal
-
-Implement the `ACL` class that manages an ordered list of `ACLRule` objects and provides first-match-wins permission evaluation via `check()`, runtime rule mutation via `addRule()` and `removeRule()`, and a configurable default effect.
-
-## Files Involved
-
-- `src/acl.ts` -- ACL class implementation (~188 lines total including YAML loading)
-- `src/errors.ts` -- `ACLDeniedError` (used by executor, not ACL directly)
-- `src/context.ts` -- `Context` and `Identity` types consumed by `check()`
-
-## Steps (TDD)
-
-### 1. Write failing tests for ACL constructor and default behavior
-
-```typescript
-// tests/acl.test.ts
-import { describe, it, expect } from 'vitest';
-import { ACL } from '../src/acl.js';
-import type { ACLRule } from '../src/acl.js';
-
-describe('ACL constructor', () => {
-  it('should default to deny when no rules match', () => {
-    const acl = new ACL([]);
-    expect(acl.check('moduleA', 'moduleB')).toBe(false);
-  });
-
-  it('should respect custom default effect', () => {
-    const acl = new ACL([], 'allow');
-    expect(acl.check('moduleA', 'moduleB')).toBe(true);
-  });
-});
-```
-
-### 2. Implement constructor with rules copy and default effect
-
-```typescript
-export class ACL {
-  private _rules: ACLRule[];
-  private _defaultEffect: string;
-
-  constructor(rules: ACLRule[], defaultEffect: string = 'deny') {
-    this._rules = [...rules];
-    this._defaultEffect = defaultEffect;
-  }
-}
-```
-
-### 3. Write failing tests for check() first-match-wins
-
-```typescript
-describe('ACL.check()', () => {
-  it('should allow when first matching rule has allow effect', () => {
-    const rules: ACLRule[] = [
-      { callers: ['moduleA'], targets: ['moduleB'], effect: 'allow', description: 'test' },
-    ];
-    const acl = new ACL(rules);
-    expect(acl.check('moduleA', 'moduleB')).toBe(true);
-  });
-
-  it('should deny when first matching rule has deny effect', () => {
-    const rules: ACLRule[] = [
-      { callers: ['moduleA'], targets: ['moduleB'], effect: 'deny', description: 'test' },
-    ];
-    const acl = new ACL(rules);
-    expect(acl.check('moduleA', 'moduleB')).toBe(false);
-  });
-
-  it('should normalize null caller to @external', () => {
-    const rules: ACLRule[] = [
-      { callers: ['@external'], targets: ['auth'], effect: 'allow', description: 'test' },
-    ];
-    const acl = new ACL(rules);
-    expect(acl.check(null, 'auth')).toBe(true);
-  });
-
-  it('should use first matching rule and ignore later rules', () => {
-    const rules: ACLRule[] = [
-      { callers: ['moduleA'], targets: ['moduleB'], effect: 'deny', description: 'deny first' },
-      { callers: ['moduleA'], targets: ['moduleB'], effect: 'allow', description: 'allow second' },
-    ];
-    const acl = new ACL(rules);
-    expect(acl.check('moduleA', 'moduleB')).toBe(false);
-  });
-
-  it('should fall through to default when no rules match', () => {
-    const rules: ACLRule[] = [
-      { callers: ['moduleX'], targets: ['moduleY'], effect: 'allow', description: 'unrelated' },
-    ];
-    const acl = new ACL(rules, 'deny');
-    expect(acl.check('moduleA', 'moduleB')).toBe(false);
-  });
-});
-```
-
-### 4. Implement check() with _matchesRule and _matchPattern
-
-```typescript
-check(callerId: string | null, targetId: string, context?: Context | null): boolean {
-  const effectiveCaller = callerId === null ? '@external' : callerId;
-  const rules = [...this._rules];
-
-  for (const rule of rules) {
-    if (this._matchesRule(rule, effectiveCaller, targetId, context ?? null)) {
-      return rule.effect === 'allow';
-    }
-  }
-
-  return this._defaultEffect === 'allow';
-}
-
-private _matchPattern(pattern: string, value: string, context: Context | null): boolean {
-  if (pattern === '@external') return value === '@external';
-  if (pattern === '@system') {
-    return context !== null && context.identity !== null && context.identity.type === 'system';
-  }
-  return matchPattern(pattern, value);
-}
-
-private _matchesRule(rule: ACLRule, caller: string, target: string, context: Context | null): boolean {
-  const callerMatch = rule.callers.some((p) => this._matchPattern(p, caller, context));
-  if (!callerMatch) return false;
-
-  const targetMatch = rule.targets.some((p) => this._matchPattern(p, target, context));
-  if (!targetMatch) return false;
-
-  if (rule.conditions != null) {
-    if (!this._checkConditions(rule.conditions, context)) return false;
-  }
-
-  return true;
-}
-```
-
-### 5. Write failing tests for addRule() and removeRule()
-
-```typescript
-describe('ACL.addRule()', () => {
-  it('should prepend rule to beginning of list', () => {
-    const acl = new ACL([
-      { callers: ['*'], targets: ['*'], effect: 'deny', description: 'deny all' },
-    ]);
-    acl.addRule({ callers: ['moduleA'], targets: ['moduleB'], effect: 'allow', description: 'allow A->B' });
-    // New rule is first, so it should match before the deny-all
-    expect(acl.check('moduleA', 'moduleB')).toBe(true);
-  });
-});
-
-describe('ACL.removeRule()', () => {
-  it('should remove rule matching callers and targets', () => {
-    const acl = new ACL([
-      { callers: ['moduleA'], targets: ['moduleB'], effect: 'allow', description: 'test' },
-    ]);
-    const removed = acl.removeRule(['moduleA'], ['moduleB']);
-    expect(removed).toBe(true);
-    expect(acl.check('moduleA', 'moduleB')).toBe(false); // falls to default deny
-  });
-
-  it('should return false when no matching rule found', () => {
-    const acl = new ACL([]);
-    expect(acl.removeRule(['moduleA'], ['moduleB'])).toBe(false);
-  });
-
-  it('should use JSON.stringify for array comparison', () => {
-    const acl = new ACL([
-      { callers: ['a', 'b'], targets: ['c'], effect: 'allow', description: 'test' },
-    ]);
-    // Different order should not match
-    expect(acl.removeRule(['b', 'a'], ['c'])).toBe(false);
-    // Same order should match
-    expect(acl.removeRule(['a', 'b'], ['c'])).toBe(true);
-  });
-});
-```
-
-### 6. Implement addRule() and removeRule()
-
-```typescript
-addRule(rule: ACLRule): void {
-  this._rules.unshift(rule);
-}
-
-removeRule(callers: string[], targets: string[]): boolean {
-  for (let i = 0; i < this._rules.length; i++) {
-    const rule = this._rules[i];
-    if (
-      JSON.stringify(rule.callers) === JSON.stringify(callers) &&
-      JSON.stringify(rule.targets) === JSON.stringify(targets)
-    ) {
-      this._rules.splice(i, 1);
-      return true;
-    }
-  }
-  return false;
-}
-```
-
-### 7. Run full test suite and type-check
-
-Run `tsc --noEmit` and `vitest` to confirm everything passes.
-
-## Acceptance Criteria
-
-- [x] `ACL` constructor accepts `rules` array and optional `defaultEffect` (default `'deny'`)
-- [x] Constructor shallow-copies the rules array to prevent external mutation
-- [x] `check()` returns `boolean` using first-match-wins evaluation
-- [x] Null `callerId` is normalized to `'@external'`
-- [x] `@external` pattern matches only the `@external` sentinel value
-- [x] `@system` pattern checks `context.identity.type === 'system'`
-- [x] Non-special patterns delegate to `matchPattern()` from `utils/pattern.ts`
-- [x] Falls through to `_defaultEffect` when no rule matches
-- [x] `addRule()` prepends the rule to the beginning of the list
-- [x] `removeRule()` uses `JSON.stringify` for caller/target array comparison and returns `boolean`
-- [x] `removeRule()` only removes the first matching rule
-- [x] All tests pass with `vitest`; zero errors from `tsc --noEmit`
-
-## Dependencies
-
-- **acl-rule** -- ACLRule interface definition
-- **pattern-matching** -- matchPattern() utility
-- **conditional-rules** -- _checkConditions() method
-
-## Estimated Time
-
-3 hours

package/planning/acl-system/tasks/acl-rule.md

@@ -1,92 +0,0 @@
-# Task: ACLRule Interface Definition
-
-## Goal
-
-Define the `ACLRule` TypeScript interface that represents a single access control rule, specifying caller patterns, target patterns, an effect (allow/deny), a human-readable description, and optional conditions for conditional evaluation.
-
-## Files Involved
-
-- `src/acl.ts` -- Interface definition exported alongside the ACL class
-
-## Steps (TDD)
-
-### 1. Write failing tests for ACLRule shape
-
-```typescript
-// tests/acl.test.ts
-import { describe, it, expect } from 'vitest';
-import type { ACLRule } from '../src/acl.js';
-
-describe('ACLRule interface', () => {
-  it('should accept a fully-specified rule', () => {
-    const rule: ACLRule = {
-      callers: ['moduleA', 'moduleB'],
-      targets: ['moduleC'],
-      effect: 'allow',
-      description: 'Allow A and B to call C',
-      conditions: { roles: ['admin'] },
-    };
-    expect(rule.callers).toEqual(['moduleA', 'moduleB']);
-    expect(rule.targets).toEqual(['moduleC']);
-    expect(rule.effect).toBe('allow');
-    expect(rule.description).toBe('Allow A and B to call C');
-    expect(rule.conditions).toEqual({ roles: ['admin'] });
-  });
-
-  it('should accept a rule with no conditions', () => {
-    const rule: ACLRule = {
-      callers: ['*'],
-      targets: ['*'],
-      effect: 'deny',
-      description: 'Deny all by default',
-    };
-    expect(rule.conditions).toBeUndefined();
-  });
-
-  it('should accept null conditions', () => {
-    const rule: ACLRule = {
-      callers: ['@external'],
-      targets: ['auth.*'],
-      effect: 'allow',
-      description: 'Allow external to auth modules',
-      conditions: null,
-    };
-    expect(rule.conditions).toBeNull();
-  });
-});
-```
-
-### 2. Define the ACLRule interface
-
-```typescript
-// src/acl.ts
-export interface ACLRule {
-  callers: string[];
-  targets: string[];
-  effect: string;
-  description: string;
-  conditions?: Record<string, unknown> | null;
-}
-```
-
-### 3. Verify type-check and tests pass
-
-Run `tsc --noEmit` to confirm no type errors, then run `vitest` to confirm all tests pass.
-
-## Acceptance Criteria
-
-- [x] `ACLRule` interface is exported from `src/acl.ts`
-- [x] `callers` is `string[]` representing caller module ID patterns
-- [x] `targets` is `string[]` representing target module ID patterns
-- [x] `effect` is `string` (validated as `'allow'` | `'deny'` at runtime during YAML loading)
-- [x] `description` is `string` for human-readable rule documentation
-- [x] `conditions` is optional `Record<string, unknown> | null` for conditional evaluation
-- [x] All tests pass with `vitest`; zero errors from `tsc --noEmit`
-
-## Dependencies
-
-- None (this is a standalone type definition)
-
-## Estimated Time
-
-1 hour

package/planning/acl-system/tasks/conditional-rules.md

@@ -1,259 +0,0 @@
-# Task: Conditional Rule Evaluation (_checkConditions)
-
-## Goal
-
-Implement the `_checkConditions()` private method on the `ACL` class that evaluates optional conditions attached to ACL rules. Conditions use AND logic: all present condition keys must pass for the rule to match. Supported conditions are `identity_types`, `roles`, and `max_call_depth`.
-
-## Files Involved
-
-- `src/acl.ts` -- `_checkConditions()` private method on the ACL class
-- `src/context.ts` -- `Context` class (provides `identity` and `callChain`) and `Identity` interface (provides `type` and `roles`)
-
-## Steps (TDD)
-
-### 1. Write failing tests for identity_types condition
-
-```typescript
-// tests/acl.test.ts
-import { describe, it, expect } from 'vitest';
-import { ACL } from '../src/acl.js';
-import type { ACLRule } from '../src/acl.js';
-import type { Context } from '../src/context.js';
-
-// Helper to create a minimal mock context
-function mockContext(overrides: {
-  identityType?: string;
-  identityRoles?: string[];
-  callChainLength?: number;
-} = {}): Context {
-  return {
-    identity: overrides.identityType !== undefined ? {
-      id: 'test-user',
-      type: overrides.identityType,
-      roles: overrides.identityRoles ?? [],
-      attrs: {},
-    } : null,
-    callChain: Array(overrides.callChainLength ?? 0).fill('module'),
-  } as unknown as Context;
-}
-
-describe('_checkConditions via check()', () => {
-  describe('identity_types condition', () => {
-    const rules: ACLRule[] = [
-      {
-        callers: ['*'],
-        targets: ['admin.*'],
-        effect: 'allow',
-        description: 'Allow system callers',
-        conditions: { identity_types: ['system', 'service'] },
-      },
-    ];
-
-    it('should allow when identity type matches', () => {
-      const acl = new ACL(rules);
-      const ctx = mockContext({ identityType: 'system' });
-      expect(acl.check('moduleA', 'admin.panel', ctx)).toBe(true);
-    });
-
-    it('should deny when identity type does not match', () => {
-      const acl = new ACL(rules);
-      const ctx = mockContext({ identityType: 'user' });
-      expect(acl.check('moduleA', 'admin.panel', ctx)).toBe(false);
-    });
-
-    it('should deny when identity is null', () => {
-      const acl = new ACL(rules);
-      const ctx = { identity: null, callChain: [] } as unknown as Context;
-      expect(acl.check('moduleA', 'admin.panel', ctx)).toBe(false);
-    });
-  });
-});
-```
-
-### 2. Write failing tests for roles condition
-
-```typescript
-  describe('roles condition', () => {
-    const rules: ACLRule[] = [
-      {
-        callers: ['*'],
-        targets: ['admin.*'],
-        effect: 'allow',
-        description: 'Allow admin role',
-        conditions: { roles: ['admin', 'superadmin'] },
-      },
-    ];
-
-    it('should allow when identity has at least one matching role', () => {
-      const acl = new ACL(rules);
-      const ctx = mockContext({ identityType: 'user', identityRoles: ['admin'] });
-      expect(acl.check('moduleA', 'admin.panel', ctx)).toBe(true);
-    });
-
-    it('should deny when identity has no matching roles', () => {
-      const acl = new ACL(rules);
-      const ctx = mockContext({ identityType: 'user', identityRoles: ['viewer'] });
-      expect(acl.check('moduleA', 'admin.panel', ctx)).toBe(false);
-    });
-
-    it('should deny when identity is null', () => {
-      const acl = new ACL(rules);
-      const ctx = { identity: null, callChain: [] } as unknown as Context;
-      expect(acl.check('moduleA', 'admin.panel', ctx)).toBe(false);
-    });
-  });
-```
-
-### 3. Write failing tests for max_call_depth condition
-
-```typescript
-  describe('max_call_depth condition', () => {
-    const rules: ACLRule[] = [
-      {
-        callers: ['*'],
-        targets: ['recursive.*'],
-        effect: 'allow',
-        description: 'Allow with depth limit',
-        conditions: { max_call_depth: 3 },
-      },
-    ];
-
-    it('should allow when call chain is within limit', () => {
-      const acl = new ACL(rules);
-      const ctx = mockContext({ identityType: 'user', callChainLength: 2 });
-      expect(acl.check('moduleA', 'recursive.handler', ctx)).toBe(true);
-    });
-
-    it('should allow when call chain is exactly at limit', () => {
-      const acl = new ACL(rules);
-      const ctx = mockContext({ identityType: 'user', callChainLength: 3 });
-      expect(acl.check('moduleA', 'recursive.handler', ctx)).toBe(true);
-    });
-
-    it('should deny when call chain exceeds limit', () => {
-      const acl = new ACL(rules);
-      const ctx = mockContext({ identityType: 'user', callChainLength: 4 });
-      expect(acl.check('moduleA', 'recursive.handler', ctx)).toBe(false);
-    });
-  });
-```
-
-### 4. Write failing tests for AND logic across multiple conditions
-
-```typescript
-  describe('AND logic across conditions', () => {
-    const rules: ACLRule[] = [
-      {
-        callers: ['*'],
-        targets: ['sensitive.*'],
-        effect: 'allow',
-        description: 'Require admin role AND system type AND depth <= 2',
-        conditions: {
-          identity_types: ['system'],
-          roles: ['admin'],
-          max_call_depth: 2,
-        },
-      },
-    ];
-
-    it('should allow when all conditions pass', () => {
-      const acl = new ACL(rules);
-      const ctx = mockContext({ identityType: 'system', identityRoles: ['admin'], callChainLength: 1 });
-      expect(acl.check('moduleA', 'sensitive.data', ctx)).toBe(true);
-    });
-
-    it('should deny when one condition fails (wrong type)', () => {
-      const acl = new ACL(rules);
-      const ctx = mockContext({ identityType: 'user', identityRoles: ['admin'], callChainLength: 1 });
-      expect(acl.check('moduleA', 'sensitive.data', ctx)).toBe(false);
-    });
-
-    it('should deny when one condition fails (wrong role)', () => {
-      const acl = new ACL(rules);
-      const ctx = mockContext({ identityType: 'system', identityRoles: ['viewer'], callChainLength: 1 });
-      expect(acl.check('moduleA', 'sensitive.data', ctx)).toBe(false);
-    });
-
-    it('should deny when one condition fails (depth exceeded)', () => {
-      const acl = new ACL(rules);
-      const ctx = mockContext({ identityType: 'system', identityRoles: ['admin'], callChainLength: 5 });
-      expect(acl.check('moduleA', 'sensitive.data', ctx)).toBe(false);
-    });
-  });
-```
-
-### 5. Write failing test for null context with conditions
-
-```typescript
-  describe('null context with conditions', () => {
-    it('should deny when context is null and conditions are present', () => {
-      const rules: ACLRule[] = [
-        {
-          callers: ['*'],
-          targets: ['*'],
-          effect: 'allow',
-          description: 'conditional rule',
-          conditions: { roles: ['admin'] },
-        },
-      ];
-      const acl = new ACL(rules);
-      expect(acl.check('moduleA', 'moduleB', null)).toBe(false);
-    });
-  });
-```
-
-### 6. Implement _checkConditions()
-
-```typescript
-private _checkConditions(conditions: Record<string, unknown>, context: Context | null): boolean {
-  // Null context cannot satisfy any conditions
-  if (context === null) return false;
-
-  // identity_types: caller's identity.type must be in the list
-  if ('identity_types' in conditions) {
-    const types = conditions['identity_types'] as string[];
-    if (context.identity === null || !types.includes(context.identity.type)) return false;
-  }
-
-  // roles: caller's identity must have at least one matching role (OR within roles, AND with other conditions)
-  if ('roles' in conditions) {
-    const roles = conditions['roles'] as string[];
-    if (context.identity === null) return false;
-    const identityRoles = new Set(context.identity.roles);
-    if (!roles.some((r) => identityRoles.has(r))) return false;
-  }
-
-  // max_call_depth: call chain length must not exceed the limit
-  if ('max_call_depth' in conditions) {
-    const maxDepth = conditions['max_call_depth'] as number;
-    if (context.callChain.length > maxDepth) return false;
-  }
-
-  return true;
-}
-```
-
-### 7. Run full test suite and type-check
-
-Run `tsc --noEmit` and `vitest` to confirm everything passes.
-
-## Acceptance Criteria
-
-- [x] `_checkConditions()` returns `false` when context is `null`
-- [x] `identity_types` condition checks `context.identity.type` is in the allowed list
-- [x] `identity_types` returns `false` when `context.identity` is `null`
-- [x] `roles` condition checks that at least one role in the condition list matches a role in `context.identity.roles` (OR within roles)
-- [x] `roles` returns `false` when `context.identity` is `null`
-- [x] `roles` uses `Set` for efficient lookup on the identity's roles
-- [x] `max_call_depth` condition checks `context.callChain.length <= maxDepth`
-- [x] Multiple conditions use AND logic: all present conditions must pass
-- [x] Unknown condition keys are silently ignored (forward-compatible)
-- [x] All tests pass with `vitest`; zero errors from `tsc --noEmit`
-
-## Dependencies
-
-- **acl-rule** -- ACLRule interface (conditions field definition)
-
-## Estimated Time
-
-2 hours