ont-run 0.0.1 → 0.0.3

package/dist/src/config/categorical.d.ts

@@ -3,6 +3,10 @@ import { z } from "zod";
  * Symbol for storing fieldFrom metadata on Zod schemas
  */
 export declare const FIELD_FROM_METADATA: unique symbol;
+/**
+ * Symbol for storing userContext metadata on Zod schemas
+ */
+export declare const USER_CONTEXT_METADATA: unique symbol;
 /**
  * Metadata stored on fieldFrom Zod schemas
  */
@@ -74,3 +78,58 @@ export declare function hasFieldFromMetadata(schema: unknown): schema is FieldFr
  * Extract fieldFrom metadata from a Zod schema
  */
 export declare function getFieldFromMetadata(schema: unknown): FieldFromMetadata | null;
+/**
+ * Type for a Zod schema with userContext metadata
+ */
+export type UserContextSchema<T extends z.ZodType> = T & {
+    [USER_CONTEXT_METADATA]: true;
+};
+/**
+ * Mark a schema as user context that will be injected at runtime.
+ *
+ * Fields marked with `userContext()` are:
+ * - **Injected**: Populated from `auth()` result's `user` field
+ * - **Hidden**: Not exposed in public API/MCP schemas
+ * - **Type-safe**: Resolver receives typed user object
+ *
+ * @param schema - Zod schema for the user context shape
+ *
+ * @example
+ * ```ts
+ * defineOntology({
+ *   auth: async (req) => {
+ *     const user = await verifyToken(req);
+ *     return {
+ *       groups: user.isAdmin ? ['admin'] : ['user'],
+ *       user: { id: user.id, email: user.email }
+ *     };
+ *   },
+ *
+ *   functions: {
+ *     editPost: {
+ *       description: 'Edit a post',
+ *       access: ['user', 'admin'],
+ *       entities: ['Post'],
+ *       inputs: z.object({
+ *         postId: z.string(),
+ *         title: z.string(),
+ *         currentUser: userContext(z.object({
+ *           id: z.string(),
+ *           email: z.string(),
+ *         })),
+ *       }),
+ *       resolver: './resolvers/editPost.ts',
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export declare function userContext<T extends z.ZodType>(schema: T): UserContextSchema<T>;
+/**
+ * Check if a Zod schema has userContext metadata
+ */
+export declare function hasUserContextMetadata(schema: unknown): schema is UserContextSchema<z.ZodType>;
+/**
+ * Get all userContext field names from a Zod object schema
+ */
+export declare function getUserContextFields(schema: z.ZodType): string[];

package/dist/src/config/index.d.ts

@@ -1,4 +1,4 @@
 export { defineOntology } from "./define.js";
-export { fieldFrom } from "./categorical.js";
-export type { OntologyConfig, FunctionDefinition, AccessGroupConfig, EnvironmentConfig, EntityDefinition, AuthFunction, ResolverContext, ResolverFunction, FieldOption, } from "./types.js";
-export { OntologyConfigSchema, FunctionDefinitionSchema, AccessGroupConfigSchema, EnvironmentConfigSchema, EntityDefinitionSchema, validateAccessGroups, validateEntityReferences, validateFieldFromReferences, } from "./schema.js";
+export { fieldFrom, userContext } from "./categorical.js";
+export type { OntologyConfig, FunctionDefinition, AccessGroupConfig, EnvironmentConfig, EntityDefinition, AuthFunction, AuthResult, ResolverContext, ResolverFunction, FieldOption, } from "./types.js";
+export { OntologyConfigSchema, FunctionDefinitionSchema, AccessGroupConfigSchema, EnvironmentConfigSchema, EntityDefinitionSchema, validateAccessGroups, validateEntityReferences, validateFieldFromReferences, validateUserContextRequirements, } from "./schema.js";

package/dist/src/config/schema.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import type { OntologyConfig } from "./types.js";
 /**
  * Schema for environment configuration
  */
@@ -160,3 +161,11 @@ export declare function validateEntityReferences(config: z.infer<typeof Ontology
  * Validate that all fieldFrom() references point to existing functions
  */
 export declare function validateFieldFromReferences(config: z.infer<typeof OntologyConfigSchema>): void;
+/**
+ * Validate that functions using userContext() will receive user data from auth.
+ * This does a runtime check by calling auth with a mock request to verify it returns
+ * an AuthResult with a user field.
+ *
+ * @param config - The full OntologyConfig (needed for the actual auth function)
+ */
+export declare function validateUserContextRequirements(config: OntologyConfig): Promise<void>;

package/dist/src/config/types.d.ts

@@ -50,9 +50,21 @@ export interface FunctionDefinition<TGroups extends string = string, TEntities e
     resolver: string;
 }
 /**
- * Auth function that determines access groups for a request
+ * Result returned by the auth function
  */
-export type AuthFunction = (req: Request) => Promise<string[]> | string[];
+export interface AuthResult {
+    /** Access groups for the current request */
+    groups: string[];
+    /** Optional user identity for row-level access control */
+    user?: Record<string, unknown>;
+}
+/**
+ * Auth function that determines access groups for a request.
+ * Can return either:
+ * - `string[]` - just group names (backwards compatible)
+ * - `AuthResult` - groups plus optional user identity
+ */
+export type AuthFunction = (req: Request) => Promise<string[] | AuthResult> | string[] | AuthResult;
 /**
  * The main Ontology configuration object
  */

package/dist/src/index.d.ts

@@ -30,8 +30,8 @@
  * ```
  */
 export { defineOntology } from "./config/define.js";
-export { fieldFrom } from "./config/categorical.js";
+export { fieldFrom, userContext } from "./config/categorical.js";
 export { startOnt } from "./server/start.js";
 export type { StartOntOptions, StartOntResult } from "./server/start.js";
-export type { OntologyConfig, FunctionDefinition, AccessGroupConfig, EnvironmentConfig, EntityDefinition, AuthFunction, ResolverContext, ResolverFunction, FieldOption, } from "./config/types.js";
+export type { OntologyConfig, FunctionDefinition, AccessGroupConfig, EnvironmentConfig, EntityDefinition, AuthFunction, AuthResult, ResolverContext, ResolverFunction, FieldOption, } from "./config/types.js";
 export { z } from "zod";

package/dist/src/lockfile/types.d.ts

@@ -23,6 +23,8 @@ export interface FunctionShape {
     outputsSchema?: Record<string, unknown>;
     /** Fields that reference other functions for their options */
     fieldReferences?: FieldReference[];
+    /** Whether this function uses userContext() for row-level access control */
+    usesUserContext?: boolean;
 }
 /**
  * Complete snapshot of the ontology
@@ -66,6 +68,8 @@ export interface FunctionChange {
     oldEntities?: string[];
     newEntities?: string[];
     fieldReferencesChanged?: boolean;
+    userContextChanged?: boolean;
+    usesUserContext?: boolean;
 }
 /**
  * Diff between old and new ontology

package/dist/src/server/api/middleware.d.ts

@@ -1,10 +1,16 @@
-import type { OntologyConfig, ResolverContext, EnvironmentConfig } from "../../config/types.js";
+import type { OntologyConfig, ResolverContext, EnvironmentConfig, AuthResult } from "../../config/types.js";
+/**
+ * Normalize auth function result to AuthResult format.
+ * Supports both legacy string[] format and new AuthResult object.
+ */
+export declare function normalizeAuthResult(result: string[] | AuthResult): AuthResult;
 /**
  * Context variables added by middleware
  */
 export interface OntologyVariables {
     resolverContext: ResolverContext;
     accessGroups: string[];
+    authResult: AuthResult;
 }
 /**
  * Create auth middleware that calls the user's auth function

package/dist/src/server/mcp/tools.d.ts

@@ -1,4 +1,4 @@
-import type { OntologyConfig, EnvironmentConfig } from "../../config/types.js";
+import type { OntologyConfig, EnvironmentConfig, AuthResult } from "../../config/types.js";
 import { type Logger } from "../resolver.js";
 /**
  * Field reference info for MCP tools
@@ -30,6 +30,6 @@ export declare function generateMcpTools(config: OntologyConfig): McpTool[];
  */
 export declare function filterToolsByAccess(tools: McpTool[], accessGroups: string[]): McpTool[];
 /**
- * Create a tool executor function that accepts per-request access groups
+ * Create a tool executor function that accepts per-request auth result
  */
-export declare function createToolExecutor(config: OntologyConfig, configDir: string, env: string, envConfig: EnvironmentConfig, logger: Logger): (toolName: string, args: unknown, accessGroups: string[]) => Promise<unknown>;
+export declare function createToolExecutor(config: OntologyConfig, configDir: string, env: string, envConfig: EnvironmentConfig, logger: Logger): (toolName: string, args: unknown, authResult: AuthResult) => Promise<unknown>;

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "ont-run",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Ontology-enforced API framework for AI coding agents",
   "type": "module",
   "bin": {
-    "ont": "./dist/bin/ont.js"
+    "ont-run": "./dist/bin/ont.js"
   },
   "exports": {
     ".": {

package/src/browser/server.ts

@@ -407,6 +407,27 @@ function generateBrowserUI(graphData: EnhancedGraphData): string {
       color: var(--change-modified);
     }
 
+    /* User Context Badge */
+    .user-context-badge {
+      display: inline-flex;
+      align-items: center;
+      gap: 4px;
+      padding: 2px 8px;
+      border-radius: 9999px;
+      font-size: 10px;
+      font-weight: 500;
+      background: rgba(21, 168, 168, 0.12);
+      color: var(--vanna-teal);
+      text-transform: uppercase;
+      letter-spacing: 0.03em;
+      margin-left: 8px;
+    }
+
+    .user-context-badge svg {
+      width: 12px;
+      height: 12px;
+    }
+
     /* Review Footer */
     .review-footer {
       position: fixed;
@@ -1875,9 +1896,14 @@ function generateBrowserUI(graphData: EnhancedGraphData): string {
         ? \`<span class="detail-change-badge \${changeStatus}">\${changeStatus === 'added' ? 'New' : changeStatus === 'removed' ? 'Removed' : 'Modified'}</span>\`
         : '';
 
+      // Build user context badge if applicable
+      const userContextBadge = data.metadata?.usesUserContext
+        ? \`<span class="user-context-badge"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M20 21v-2a4 4 0 0 0-4-4H8a4 4 0 0 0-4 4v2"/><circle cx="12" cy="7" r="4"/></svg>User Context</span>\`
+        : '';
+
       let html = \`
         <div class="detail-header">
-          <div class="detail-type \${data.type}">\${formatType(data.type)}\${changeBadge}</div>
+          <div class="detail-type \${data.type}">\${formatType(data.type)}\${changeBadge}\${userContextBadge}</div>
           <div class="detail-name">\${data.label}</div>
           <div class="detail-description">\${data.description || 'No description'}</div>
         </div>

package/src/browser/transform.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { zodToJsonSchema } from "zod-to-json-schema";
 import type { OntologyConfig } from "../config/types.js";
 import type { OntologyDiff, FunctionChange } from "../lockfile/types.js";
-import { getFieldFromMetadata } from "../config/categorical.js";
+import { getFieldFromMetadata, getUserContextFields } from "../config/categorical.js";
 
 export type NodeType = "entity" | "function" | "accessGroup";
 export type EdgeType = "operates-on" | "requires-access" | "depends-on";
@@ -18,6 +18,7 @@ export interface GraphNode {
     outputs?: Record<string, unknown>;
     resolver?: string;
     functionCount?: number;
+    usesUserContext?: boolean;
   };
 }
 
@@ -154,6 +155,10 @@ export function transformToGraphData(config: OntologyConfig): GraphData {
       entityCounts[entity] = (entityCounts[entity] || 0) + 1;
     }
 
+    // Check if function uses userContext
+    const userContextFields = getUserContextFields(fn.inputs);
+    const usesUserContext = userContextFields.length > 0;
+
     // Create function node
     nodes.push({
       id: `function:${name}`,
@@ -164,6 +169,7 @@ export function transformToGraphData(config: OntologyConfig): GraphData {
         inputs: safeZodToJsonSchema(fn.inputs),
         outputs: fn.outputs ? safeZodToJsonSchema(fn.outputs) : undefined,
         resolver: fn.resolver,
+        usesUserContext: usesUserContext || undefined,
       },
     });
 

package/src/cli/commands/init.ts

@@ -51,7 +51,7 @@ export const initCommand = defineCommand({
     }
 
     // Write ontology.config.ts
-    const configTemplate = `import { defineOntology } from 'ont-run';
+    const configTemplate = `import { defineOntology, userContext } from 'ont-run';
 import { z } from 'zod';
 
 export default defineOntology({
@@ -63,13 +63,22 @@ export default defineOntology({
   },
 
   // Pluggable auth - customize this for your use case
+  // Return { groups, user } for row-level access control
   auth: async (req) => {
     const token = req.headers.get('Authorization');
-    // Return access groups based on auth
+    // Return access groups and optional user data
     // This is where you'd verify JWTs, API keys, etc.
-    if (!token) return ['public'];
-    if (token === 'admin-secret') return ['admin', 'support', 'public'];
-    return ['support', 'public'];
+    if (!token) return { groups: ['public'] };
+    if (token === 'admin-secret') {
+      return {
+        groups: ['admin', 'support', 'public'],
+        user: { id: 'admin-1', email: 'admin@example.com' },
+      };
+    }
+    return {
+      groups: ['support', 'public'],
+      user: { id: 'user-1', email: 'user@example.com' },
+    };
   },
 
   accessGroups: {
@@ -78,21 +87,32 @@ export default defineOntology({
     admin: { description: 'Administrators' },
   },
 
+  entities: {
+    User: { description: 'A user account' },
+  },
+
   functions: {
     // Example: Public function
     healthCheck: {
       description: 'Check API health status',
       access: ['public', 'support', 'admin'],
+      entities: [],
       inputs: z.object({}),
       resolver: './resolvers/healthCheck.ts',
     },
 
-    // Example: Restricted function
+    // Example: Restricted function with row-level access
     getUser: {
       description: 'Get user details by ID',
       access: ['support', 'admin'],
+      entities: ['User'],
       inputs: z.object({
         userId: z.string().uuid(),
+        // currentUser is injected from auth - not visible to API callers
+        currentUser: userContext(z.object({
+          id: z.string(),
+          email: z.string(),
+        })),
       }),
       resolver: './resolvers/getUser.ts',
     },
@@ -101,6 +121,7 @@ export default defineOntology({
     deleteUser: {
       description: 'Delete a user account',
       access: ['admin'],
+      entities: ['User'],
       inputs: z.object({
         userId: z.string().uuid(),
         reason: z.string().optional(),
@@ -132,10 +153,21 @@ export default async function healthCheck(ctx: ResolverContext, args: {}) {
 
 interface GetUserArgs {
   userId: string;
+  currentUser: {
+    id: string;
+    email: string;
+  };
 }
 
 export default async function getUser(ctx: ResolverContext, args: GetUserArgs) {
   ctx.logger.info(\`Getting user: \${args.userId}\`);
+  ctx.logger.info(\`Requested by: \${args.currentUser.email}\`);
+
+  // Example: Check if user can access this resource
+  // Support can only view their own account
+  if (!ctx.accessGroups.includes('admin') && args.userId !== args.currentUser.id) {
+    throw new Error('You can only view your own account');
+  }
 
   // This is where you'd query your database
   // Example response:

package/src/cli/utils/config-loader.ts

@@ -70,9 +70,24 @@ export async function loadConfig(configPath?: string): Promise<{
 
     return { config, configDir, configPath: resolvedPath };
   } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ERR_MODULE_NOT_FOUND") {
-      throw new Error(`Failed to load config: ${resolvedPath}`);
+    const err = error as NodeJS.ErrnoException & { message?: string };
+    if (err.code === "ERR_MODULE_NOT_FOUND") {
+      // Check if it's a missing dependency vs missing config
+      const message = err.message || "";
+      if (message.includes("ont-run") || message.includes("zod")) {
+        throw new Error(
+          `Failed to load config: ${resolvedPath}\n\n` +
+            `Missing dependencies. Run 'bun install' first.`
+        );
+      }
+      throw new Error(
+        `Failed to load config: ${resolvedPath}\n\n` +
+          `Module not found: ${message}`
+      );
     }
-    throw error;
+    throw new Error(
+      `Failed to load config: ${resolvedPath}\n\n` +
+        `${err.message || error}`
+    );
   }
 }

package/src/config/categorical.ts

@@ -5,6 +5,11 @@ import { z } from "zod";
  */
 export const FIELD_FROM_METADATA = Symbol.for("ont:fieldFrom");
 
+/**
+ * Symbol for storing userContext metadata on Zod schemas
+ */
+export const USER_CONTEXT_METADATA = Symbol.for("ont:userContext");
+
 /**
  * Metadata stored on fieldFrom Zod schemas
  */
@@ -99,3 +104,88 @@ export function getFieldFromMetadata(
   }
   return null;
 }
+
+/**
+ * Type for a Zod schema with userContext metadata
+ */
+export type UserContextSchema<T extends z.ZodType> = T & {
+  [USER_CONTEXT_METADATA]: true;
+};
+
+/**
+ * Mark a schema as user context that will be injected at runtime.
+ *
+ * Fields marked with `userContext()` are:
+ * - **Injected**: Populated from `auth()` result's `user` field
+ * - **Hidden**: Not exposed in public API/MCP schemas
+ * - **Type-safe**: Resolver receives typed user object
+ *
+ * @param schema - Zod schema for the user context shape
+ *
+ * @example
+ * ```ts
+ * defineOntology({
+ *   auth: async (req) => {
+ *     const user = await verifyToken(req);
+ *     return {
+ *       groups: user.isAdmin ? ['admin'] : ['user'],
+ *       user: { id: user.id, email: user.email }
+ *     };
+ *   },
+ *
+ *   functions: {
+ *     editPost: {
+ *       description: 'Edit a post',
+ *       access: ['user', 'admin'],
+ *       entities: ['Post'],
+ *       inputs: z.object({
+ *         postId: z.string(),
+ *         title: z.string(),
+ *         currentUser: userContext(z.object({
+ *           id: z.string(),
+ *           email: z.string(),
+ *         })),
+ *       }),
+ *       resolver: './resolvers/editPost.ts',
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export function userContext<T extends z.ZodType>(schema: T): UserContextSchema<T> {
+  const marked = schema as UserContextSchema<T>;
+  marked[USER_CONTEXT_METADATA] = true;
+  return marked;
+}
+
+/**
+ * Check if a Zod schema has userContext metadata
+ */
+export function hasUserContextMetadata(
+  schema: unknown
+): schema is UserContextSchema<z.ZodType> {
+  return (
+    schema !== null &&
+    typeof schema === "object" &&
+    USER_CONTEXT_METADATA in schema &&
+    (schema as Record<symbol, unknown>)[USER_CONTEXT_METADATA] === true
+  );
+}
+
+/**
+ * Get all userContext field names from a Zod object schema
+ */
+export function getUserContextFields(schema: z.ZodType): string[] {
+  const fields: string[] = [];
+
+  if (schema instanceof z.ZodObject) {
+    const shape = schema.shape;
+    for (const [key, value] of Object.entries(shape)) {
+      if (hasUserContextMetadata(value)) {
+        fields.push(key);
+      }
+    }
+  }
+
+  return fields;
+}

package/src/config/index.ts

@@ -1,5 +1,5 @@
 export { defineOntology } from "./define.js";
-export { fieldFrom } from "./categorical.js";
+export { fieldFrom, userContext } from "./categorical.js";
 export type {
   OntologyConfig,
   FunctionDefinition,
@@ -7,6 +7,7 @@ export type {
   EnvironmentConfig,
   EntityDefinition,
   AuthFunction,
+  AuthResult,
   ResolverContext,
   ResolverFunction,
   FieldOption,
@@ -20,4 +21,5 @@ export {
   validateAccessGroups,
   validateEntityReferences,
   validateFieldFromReferences,
+  validateUserContextRequirements,
 } from "./schema.js";

package/src/config/schema.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { getFieldFromMetadata } from "./categorical.js";
+import { getFieldFromMetadata, getUserContextFields } from "./categorical.js";
+import type { OntologyConfig } from "./types.js";
 
 /**
  * Schema for environment configuration
@@ -194,3 +195,65 @@ export function validateFieldFromReferences(
     }
   }
 }
+
+/**
+ * Validate that functions using userContext() will receive user data from auth.
+ * This does a runtime check by calling auth with a mock request to verify it returns
+ * an AuthResult with a user field.
+ *
+ * @param config - The full OntologyConfig (needed for the actual auth function)
+ */
+export async function validateUserContextRequirements(
+  config: OntologyConfig
+): Promise<void> {
+  // Find functions that use userContext
+  const functionsWithUserContext: string[] = [];
+
+  for (const [fnName, fn] of Object.entries(config.functions)) {
+    const userContextFields = getUserContextFields(fn.inputs as z.ZodType);
+    if (userContextFields.length > 0) {
+      functionsWithUserContext.push(fnName);
+    }
+  }
+
+  // If no functions use userContext, no validation needed
+  if (functionsWithUserContext.length === 0) {
+    return;
+  }
+
+  // Create a mock request to test the auth function
+  const mockRequest = new Request("http://localhost/test", {
+    headers: { Authorization: "test-token" },
+  });
+
+  try {
+    const authResult = await config.auth(mockRequest);
+
+    // Check if auth returns an object with user field
+    const hasUserField =
+      authResult !== null &&
+      typeof authResult === "object" &&
+      !Array.isArray(authResult) &&
+      "user" in authResult;
+
+    if (!hasUserField) {
+      throw new Error(
+        `The following functions use userContext() but auth() does not return a user object:\n` +
+          `  ${functionsWithUserContext.join(", ")}\n\n` +
+          `To fix this, update your auth function to return an AuthResult:\n` +
+          `  auth: async (req) => {\n` +
+          `    return {\n` +
+          `      groups: ['user'],\n` +
+          `      user: { id: '...', email: '...' }  // Add user data here\n` +
+          `    };\n` +
+          `  }`
+      );
+    }
+  } catch (error) {
+    // If auth throws, we can't validate - but that's ok, the error will surface at request time
+    if (error instanceof Error && error.message.includes("userContext")) {
+      throw error; // Re-throw our validation error
+    }
+    // Otherwise, auth function had an error with the mock request - skip validation
+  }
+}

package/src/config/types.ts

@@ -59,9 +59,22 @@ export interface FunctionDefinition<
 }
 
 /**
- * Auth function that determines access groups for a request
+ * Result returned by the auth function
  */
-export type AuthFunction = (req: Request) => Promise<string[]> | string[];
+export interface AuthResult {
+  /** Access groups for the current request */
+  groups: string[];
+  /** Optional user identity for row-level access control */
+  user?: Record<string, unknown>;
+}
+
+/**
+ * Auth function that determines access groups for a request.
+ * Can return either:
+ * - `string[]` - just group names (backwards compatible)
+ * - `AuthResult` - groups plus optional user identity
+ */
+export type AuthFunction = (req: Request) => Promise<string[] | AuthResult> | string[] | AuthResult;
 
 /**
  * The main Ontology configuration object

package/src/index.ts

@@ -32,7 +32,7 @@
 
 // Main API
 export { defineOntology } from "./config/define.js";
-export { fieldFrom } from "./config/categorical.js";
+export { fieldFrom, userContext } from "./config/categorical.js";
 export { startOnt } from "./server/start.js";
 export type { StartOntOptions, StartOntResult } from "./server/start.js";
 
@@ -44,6 +44,7 @@ export type {
   EnvironmentConfig,
   EntityDefinition,
   AuthFunction,
+  AuthResult,
   ResolverContext,
   ResolverFunction,
   FieldOption,