@gp2f/server 0.1.6 → 0.1.8

package/README.md

@@ -72,6 +72,34 @@ async function main() {
 main().catch(console.error);
 ```
 
+### 3. Fluent Policy Builder
+
+Build policy ASTs with a chainable API instead of raw JSON objects:
+
+```typescript
+import { p } from '@gp2f/server';
+
+// Field equality
+const policy = p.field('/role').eq('admin');
+
+// Logical AND
+const policy = p.and(
+  p.field('/role').eq('clinician'),
+  p.exists('/patient_id'),
+);
+
+// Role allow-list
+const policy = p.field('/role').in(['admin', 'editor', 'reviewer']);
+
+// Numeric comparison
+const policy = p.field('/score').gte(80);
+
+// Vibe Engine gate
+const policy = p.vibe('frustrated').withConfidence(0.8).build();
+```
+
+The builder output is a plain `AstNode` that works with `evaluate()`, `evaluateWithTrace()`, `addActivity()`, and anywhere else a policy AST is accepted.
+
 ## Development
 This package uses `napi-rs` to build the Rust bindings.
 

package/index.d.ts

@@ -1,30 +1,200 @@
-// Auto-resolve library typings for GP2F
+/* eslint-disable */
+/* tslint:disable */
+/* auto-generated – mirrors gp2f-node/src/*.rs napi exports */
 
-export interface PolicyNode {
-    kind: string;
-    path?: string;
-    value?: string;
-    children?: PolicyNode[];
+// ── Node kinds ────────────────────────────────────────────────────────────────
+
+export type NodeKind =
+    | 'LiteralTrue'
+    | 'LiteralFalse'
+    | 'And'
+    | 'Or'
+    | 'Not'
+    | 'Eq'
+    | 'Neq'
+    | 'Gt'
+    | 'Gte'
+    | 'Lt'
+    | 'Lte'
+    | 'In'
+    | 'Contains'
+    | 'Exists'
+    | 'Field'
+    | 'Call'
+    | 'VibeCheck'
+
+// ── Core AST ──────────────────────────────────────────────────────────────────
+
+/** A node in the GP2F policy AST. */
+export interface AstNode {
+    /** The operation this node performs (required). */
+    kind: string
+    /** Child nodes for composite operators (AND, OR, NOT, comparison, …). */
+    children?: AstNode[]
+    /** JSON-pointer path used by `FIELD` and `EXISTS` nodes (e.g. `/user/role`). */
+    path?: string
+    /** String-encoded scalar value for leaf nodes (e.g. `"admin"`, `"42"`). */
+    value?: string
+    /** Name of the external function – used only by `CALL` nodes. */
+    callName?: string
 }
 
+// ── Activity & server configuration ──────────────────────────────────────────
+
+/** Configuration object for a single workflow activity. */
 export interface ActivityConfig {
-    policy: PolicyNode;
+    /** Policy AST that governs whether this activity is permitted. */
+    policy: AstNode | PolicyInput
+    /** Optional name of a registered compensation handler. */
+    compensationRef?: string
+    /** When `true`, this activity runs as a Local Activity. */
+    isLocal?: boolean
+}
+
+/** Server startup configuration. */
+export interface ServerConfig {
+    /** TCP port to listen on. Defaults to 3000. */
+    port?: number
+    /** Bind address. Defaults to `"0.0.0.0"`. */
+    host?: string
+}
+
+/** Context passed to every `onExecute` callback. */
+export interface ExecutionContext {
+    /** Unique workflow execution identifier. */
+    instanceId: string
+    /** Tenant/organisation this execution belongs to. */
+    tenantId: string
+    /** Name of the activity currently executing. */
+    activityName: string
+    /** The JSON-encoded state document. Use `JSON.parse(ctx.stateJson)`. */
+    stateJson: string
 }
 
-export class JsGp2FServer {
-    constructor(config: { port?: number; host?: string });
-    register(workflow: JsWorkflow): void;
-    start(): Promise<void>;
+/** Result of a policy evaluation including the decision trace. */
+export interface EvalResult {
+    /** `true` when the policy permits the operation. */
+    result: boolean
+    /** Human-readable trace of each evaluation step (for debugging). */
+    trace: string[]
 }
 
+// ── Native functions ──────────────────────────────────────────────────────────
+
+/**
+ * Evaluate a policy AST against a JSON state object.
+ *
+ * Returns `true` when the policy permits the operation.
+ */
+export function evaluate(policy: AstNode, state: object): boolean
+
+/**
+ * Evaluate a policy AST and return the full evaluation trace.
+ *
+ * Useful for debugging policies.
+ */
+export function evaluateWithTrace(policy: AstNode, state: object): EvalResult
 
-export class JsWorkflow {
-    constructor(id: string);
+// ── Workflow class ────────────────────────────────────────────────────────────
+
+export class Workflow {
+    constructor(workflowId: string)
+
+    /** Add an activity to this workflow. */
     addActivity(
         name: string,
         config: ActivityConfig,
-        handler: (ctx: any) => Promise<void>
-    ): void;
-    activityCount(): number;
-    id(): string;
+        onExecute?: (ctx: ExecutionContext) => Promise<void> | void,
+    ): string
+
+    /** The workflow identifier. */
+    readonly id: string
+
+    /** Number of registered activities. */
+    readonly activityCount: number
+
+    /** Evaluate all activity policies against `state` (no side-effects). */
+    dryRun(state: object): boolean
+}
+
+// ── GP2FServer class ──────────────────────────────────────────────────────────
+
+export class GP2FServer {
+    constructor(config?: ServerConfig)
+
+    /** Register a workflow with this server. */
+    register(workflow: Workflow): void
+
+    /** Start the HTTP server. */
+    start(): Promise<void>
+
+    /** Stop the HTTP server. */
+    stop(): Promise<void>
+
+    /** The configured TCP port. */
+    readonly port: number
+
+    /** `true` when the server is currently accepting connections. */
+    readonly isRunning: boolean
+}
+
+// ── Fluent Policy Builder ─────────────────────────────────────────────────────
+
+/** Shared interface for all builder objects that can produce an AstNode. */
+export interface Builder {
+    build(): AstNode
+    toJSON(): AstNode
+}
+
+/** A policy value that is either a raw AstNode or a Builder. */
+export type PolicyInput = AstNode | Builder
+
+/** Builder for field-specific policy assertions. */
+export declare class FieldBuilder implements Builder {
+    constructor(path: string)
+
+    equal(value: string | number): AstNode
+    eq(value: string | number): AstNode
+    notEqual(value: string | number): AstNode
+    neq(value: string | number): AstNode
+
+    greaterThan(value: string | number): AstNode
+    gt(value: string | number): AstNode
+    greaterThanOrEqual(value: string | number): AstNode
+    gte(value: string | number): AstNode
+    lessThan(value: string | number): AstNode
+    lt(value: string | number): AstNode
+    lessThanOrEqual(value: string | number): AstNode
+    lte(value: string | number): AstNode
+
+    in(values: string[]): AstNode
+    contains(value: string): AstNode
+
+    build(): AstNode
+    toJSON(): AstNode
+}
+
+/** Builder for Semantic Vibe Engine checks. */
+export declare class VibeBuilder implements Builder {
+    constructor(intent: string)
+
+    withConfidence(threshold: number): this
+
+    build(): AstNode
+    toJSON(): AstNode
 }
+
+/** Entry point for the fluent policy builder API. */
+export declare class PolicyBuilder {
+    static field(path: string): FieldBuilder
+    static and(...nodes: PolicyInput[]): AstNode
+    static or(...nodes: PolicyInput[]): AstNode
+    static not(node: PolicyInput): AstNode
+    static exists(path: string): AstNode
+    static literalTrue(): AstNode
+    static literalFalse(): AstNode
+    static vibe(intent: string): VibeBuilder
+}
+
+/** Shorthand alias for {@link PolicyBuilder}. */
+export declare const p: typeof PolicyBuilder

package/index.js

@@ -38,14 +38,25 @@ function loadNative() {
   )
 }
 
-const nativeAddon = loadNative()
+const { p, PolicyBuilder, FieldBuilder, VibeBuilder } = require('./lib/policy-builder')
 
-module.exports = nativeAddon
+let native
+try {
+  native = loadNative()
+} catch (_) {
+  native = {}
+}
+
+module.exports = { ...native, p, PolicyBuilder, FieldBuilder, VibeBuilder }
 
 // Explicitly assign named exports so Node.js CJS-ESM bridge can statically analyze them
-module.exports.JsGp2FServer = nativeAddon.JsGp2FServer
-module.exports.JsWorkflow = nativeAddon.JsWorkflow
-module.exports.NodeKind = nativeAddon.NodeKind
-module.exports.JsServerConfig = nativeAddon.JsServerConfig
-module.exports.JsActivityConfig = nativeAddon.JsActivityConfig
-module.exports.JsAstNode = nativeAddon.JsAstNode
+module.exports.GP2FServer = native.JsGp2FServer || native.GP2FServer
+module.exports.Workflow = native.JsWorkflow || native.Workflow
+module.exports.AstNode = native.JsAstNode || native.AstNode
+module.exports.NodeKind = native.JsNodeKind || native.NodeKind
+module.exports.evaluate = native.evaluate
+module.exports.evaluateWithTrace = native.evaluateWithTrace
+module.exports.p = p
+module.exports.PolicyBuilder = PolicyBuilder
+module.exports.FieldBuilder = FieldBuilder
+module.exports.VibeBuilder = VibeBuilder

package/lib/policy-builder.js

@@ -0,0 +1,148 @@
+'use strict'
+
+/**
+ * Fluent Policy Builder API for constructing GP2F policy AST nodes.
+ *
+ * Provides a chainable alternative to writing raw JSON AST objects.
+ *
+ * @example
+ * ```js
+ * const { p } = require('@gp2f/server');
+ *
+ * const policy = p.and(
+ *   p.field('/user/role').eq('admin'),
+ *   p.exists('/session/token'),
+ * );
+ * ```
+ */
+
+// ── Internal helper ───────────────────────────────────────────────────────────
+
+function resolve(node) {
+  return node && typeof node.build === 'function' ? node.build() : node
+}
+
+// ── FieldBuilder ──────────────────────────────────────────────────────────────
+
+class FieldBuilder {
+  constructor(path) {
+    this._path = path
+  }
+
+  _op(kind, value) {
+    return {
+      kind,
+      children: [{ kind: 'Field', path: this._path }],
+      value: String(value)
+    }
+  }
+
+  // Equality
+  equal(value) { return this._op('Eq', value) }
+  eq(value) { return this.equal(value) }
+  notEqual(value) { return this._op('Neq', value) }
+  neq(value) { return this.notEqual(value) }
+
+  // Comparisons
+  greaterThan(value) { return this._op('Gt', value) }
+  gt(value) { return this.greaterThan(value) }
+  greaterThanOrEqual(value) { return this._op('Gte', value) }
+  gte(value) { return this.greaterThanOrEqual(value) }
+  lessThan(value) { return this._op('Lt', value) }
+  lt(value) { return this.lessThan(value) }
+  lessThanOrEqual(value) { return this._op('Lte', value) }
+  lte(value) { return this.lessThanOrEqual(value) }
+
+  // Collection
+  in(values) {
+    return {
+      kind: 'In',
+      children: [{ kind: 'Field', path: this._path }],
+      value: JSON.stringify(values)
+    }
+  }
+
+  contains(value) {
+    return {
+      kind: 'Contains',
+      children: [{ kind: 'Field', path: this._path }],
+      value: String(value)
+    }
+  }
+
+  build() {
+    throw new Error(
+      'FieldBuilder must be terminated with an operator (e.g. .eq(), .gt())'
+    )
+  }
+
+  toJSON() {
+    return this.build()
+  }
+}
+
+// ── VibeBuilder ───────────────────────────────────────────────────────────────
+
+class VibeBuilder {
+  constructor(intent) {
+    this._intent = intent
+    this._threshold = undefined
+  }
+
+  withConfidence(threshold) {
+    this._threshold = threshold
+    return this
+  }
+
+  build() {
+    const node = { kind: 'VibeCheck', value: this._intent }
+    if (this._threshold !== undefined) {
+      node.path = String(this._threshold)
+    }
+    return node
+  }
+
+  toJSON() {
+    return this.build()
+  }
+}
+
+// ── PolicyBuilder ─────────────────────────────────────────────────────────────
+
+class PolicyBuilder {
+  static field(path) {
+    return new FieldBuilder(path)
+  }
+
+  static and(...nodes) {
+    return { kind: 'And', children: nodes.map(resolve) }
+  }
+
+  static or(...nodes) {
+    return { kind: 'Or', children: nodes.map(resolve) }
+  }
+
+  static not(node) {
+    return { kind: 'Not', children: [resolve(node)] }
+  }
+
+  static exists(path) {
+    return { kind: 'Exists', path }
+  }
+
+  static literalTrue() {
+    return { kind: 'LiteralTrue' }
+  }
+
+  static literalFalse() {
+    return { kind: 'LiteralFalse' }
+  }
+
+  static vibe(intent) {
+    return new VibeBuilder(intent)
+  }
+}
+
+const p = PolicyBuilder
+
+module.exports = { p, PolicyBuilder, FieldBuilder, VibeBuilder }

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@gp2f/server",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Native Node.js bindings for the GP2F policy engine – powered by napi-rs",
   "main": "index.js",
   "types": "index.d.ts",
   "files": [
     "index.js",
     "index.d.ts",
+    "lib",
     "gp2f_node.*.node"
   ],
   "scripts": {