ont-run 0.0.1

package/src/config/types.ts

@@ -0,0 +1,121 @@
+import type { z } from "zod";
+
+/**
+ * Configuration for an environment (dev, test, prod)
+ */
+export interface EnvironmentConfig {
+  /** Enable debug mode */
+  debug?: boolean;
+  /** Any additional environment-specific settings */
+  [key: string]: unknown;
+}
+
+/**
+ * Configuration for an access group
+ */
+export interface AccessGroupConfig {
+  /** Description of this access group */
+  description: string;
+}
+
+/**
+ * Definition of an entity in the ontology
+ */
+export interface EntityDefinition {
+  /** Human-readable description of this entity */
+  description: string;
+}
+
+/**
+ * Option returned by functions used as field sources.
+ * Functions referenced by `fieldFrom()` should return an array of these.
+ */
+export interface FieldOption {
+  /** The stored value */
+  value: string;
+  /** Human-readable label for display */
+  label: string;
+}
+
+/**
+ * Definition of a function in the ontology
+ */
+export interface FunctionDefinition<
+  TGroups extends string = string,
+  TEntities extends string = string,
+> {
+  /** Human-readable description of what this function does */
+  description: string;
+  /** Which access groups can call this function */
+  access: TGroups[];
+  /** Which entities this function relates to (use empty array [] if none) */
+  entities: TEntities[];
+  /** Zod schema for input validation */
+  inputs: z.ZodType<unknown>;
+  /** Zod schema for output validation/documentation */
+  outputs?: z.ZodType<unknown>;
+  /** Path to the resolver file (relative to ontology.config.ts) */
+  resolver: string;
+}
+
+/**
+ * Auth function that determines access groups for a request
+ */
+export type AuthFunction = (req: Request) => Promise<string[]> | string[];
+
+/**
+ * The main Ontology configuration object
+ */
+export interface OntologyConfig<
+  TGroups extends string = string,
+  TEntities extends string = string,
+  TFunctions extends Record<
+    string,
+    FunctionDefinition<TGroups, TEntities>
+  > = Record<string, FunctionDefinition<TGroups, TEntities>>,
+> {
+  /** Name of this ontology/API */
+  name: string;
+
+  /** Environment configurations */
+  environments: Record<string, EnvironmentConfig>;
+
+  /** Pluggable auth function */
+  auth: AuthFunction;
+
+  /** Access group definitions */
+  accessGroups: Record<TGroups, AccessGroupConfig>;
+
+  /** Entity definitions for categorization */
+  entities?: Record<TEntities, EntityDefinition>;
+
+  /** Function definitions */
+  functions: TFunctions;
+}
+
+/**
+ * Context passed to resolvers
+ */
+export interface ResolverContext {
+  /** Current environment name */
+  env: string;
+  /** Environment configuration */
+  envConfig: EnvironmentConfig;
+  /** Logger instance */
+  logger: {
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+    debug: (message: string, ...args: unknown[]) => void;
+  };
+  /** Access groups for the current request */
+  accessGroups: string[];
+}
+
+/**
+ * Resolver function signature
+ */
+export type ResolverFunction<TArgs = unknown, TResult = unknown> = (
+  ctx: ResolverContext,
+  args: TArgs
+) => Promise<TResult> | TResult;

package/src/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Ontology - Ontology-first backends with human-approved AI access & edits
+ *
+ * @example
+ * ```ts
+ * import { defineOntology, fieldFrom } from 'ont-run';
+ * import { z } from 'zod';
+ *
+ * export default defineOntology({
+ *   name: 'my-api',
+ *   environments: { dev: { debug: true }, prod: { debug: false } },
+ *   auth: async (req) => req.headers.get('Authorization') ? ['admin'] : ['public'],
+ *   accessGroups: {
+ *     public: { description: 'Unauthenticated' },
+ *     admin: { description: 'Administrators' },
+ *   },
+ *   entities: {
+ *     User: { description: 'A user account' },
+ *   },
+ *   functions: {
+ *     hello: {
+ *       description: 'Say hello',
+ *       access: ['public'],
+ *       entities: [],
+ *       inputs: z.object({ name: z.string() }),
+ *       resolver: './resolvers/hello.ts',
+ *     },
+ *   },
+ * });
+ * ```
+ */
+
+// Main API
+export { defineOntology } from "./config/define.js";
+export { fieldFrom } from "./config/categorical.js";
+export { startOnt } from "./server/start.js";
+export type { StartOntOptions, StartOntResult } from "./server/start.js";
+
+// Types
+export type {
+  OntologyConfig,
+  FunctionDefinition,
+  AccessGroupConfig,
+  EnvironmentConfig,
+  EntityDefinition,
+  AuthFunction,
+  ResolverContext,
+  ResolverFunction,
+  FieldOption,
+} from "./config/types.js";
+
+// Re-export Zod for convenience
+export { z } from "zod";

package/src/lockfile/differ.ts

@@ -0,0 +1,242 @@
+import type {
+  OntologySnapshot,
+  OntologyDiff,
+  FunctionChange,
+} from "./types.js";
+import { hashOntology } from "./hasher.js";
+
+/**
+ * Compare two ontology snapshots and generate a diff.
+ * @param oldOntology - The previous ontology (from lockfile), or null if first run
+ * @param newOntology - The current ontology (from config)
+ */
+export function diffOntology(
+  oldOntology: OntologySnapshot | null,
+  newOntology: OntologySnapshot
+): OntologyDiff {
+  const newHash = hashOntology(newOntology);
+
+  // First run - no old ontology
+  if (!oldOntology) {
+    const functions: FunctionChange[] = Object.entries(
+      newOntology.functions
+    ).map(([name, fn]) => ({
+      name,
+      type: "added" as const,
+      newAccess: fn.access,
+      newDescription: fn.description,
+      newEntities: fn.entities,
+    }));
+
+    return {
+      hasChanges: true,
+      addedGroups: newOntology.accessGroups,
+      removedGroups: [],
+      addedEntities: newOntology.entities ?? [],
+      removedEntities: [],
+      functions,
+      newOntology,
+      newHash,
+    };
+  }
+
+  // Compare access groups
+  const oldGroupSet = new Set(oldOntology.accessGroups);
+  const newGroupSet = new Set(newOntology.accessGroups);
+
+  const addedGroups = newOntology.accessGroups.filter(
+    (g) => !oldGroupSet.has(g)
+  );
+  const removedGroups = oldOntology.accessGroups.filter(
+    (g) => !newGroupSet.has(g)
+  );
+
+  // Compare entities
+  const oldEntitySet = new Set(oldOntology.entities ?? []);
+  const newEntitySet = new Set(newOntology.entities ?? []);
+
+  const addedEntities = (newOntology.entities ?? []).filter(
+    (e) => !oldEntitySet.has(e)
+  );
+  const removedEntities = (oldOntology.entities ?? []).filter(
+    (e) => !newEntitySet.has(e)
+  );
+
+  // Compare functions
+  const functions: FunctionChange[] = [];
+  const oldFnNames = new Set(Object.keys(oldOntology.functions));
+  const newFnNames = new Set(Object.keys(newOntology.functions));
+
+  // Added functions
+  for (const name of newFnNames) {
+    if (!oldFnNames.has(name)) {
+      const fn = newOntology.functions[name];
+      functions.push({
+        name,
+        type: "added",
+        newAccess: fn.access,
+        newDescription: fn.description,
+      });
+    }
+  }
+
+  // Removed functions
+  for (const name of oldFnNames) {
+    if (!newFnNames.has(name)) {
+      const fn = oldOntology.functions[name];
+      functions.push({
+        name,
+        type: "removed",
+        oldAccess: fn.access,
+        oldDescription: fn.description,
+      });
+    }
+  }
+
+  // Modified functions
+  for (const name of newFnNames) {
+    if (oldFnNames.has(name)) {
+      const oldFn = oldOntology.functions[name];
+      const newFn = newOntology.functions[name];
+
+      // Check if anything changed
+      const accessChanged =
+        JSON.stringify(oldFn.access) !== JSON.stringify(newFn.access);
+      const descriptionChanged = oldFn.description !== newFn.description;
+      const inputsChanged =
+        JSON.stringify(oldFn.inputsSchema) !==
+        JSON.stringify(newFn.inputsSchema);
+      const outputsChanged =
+        JSON.stringify(oldFn.outputsSchema) !==
+        JSON.stringify(newFn.outputsSchema);
+      const entitiesChanged =
+        JSON.stringify(oldFn.entities) !== JSON.stringify(newFn.entities);
+      const fieldReferencesChanged =
+        JSON.stringify(oldFn.fieldReferences) !==
+        JSON.stringify(newFn.fieldReferences);
+
+      if (
+        accessChanged ||
+        descriptionChanged ||
+        inputsChanged ||
+        outputsChanged ||
+        entitiesChanged ||
+        fieldReferencesChanged
+      ) {
+        functions.push({
+          name,
+          type: "modified",
+          oldAccess: accessChanged ? oldFn.access : undefined,
+          newAccess: accessChanged ? newFn.access : undefined,
+          oldDescription: descriptionChanged ? oldFn.description : undefined,
+          newDescription: descriptionChanged ? newFn.description : undefined,
+          inputsChanged: inputsChanged || undefined,
+          outputsChanged: outputsChanged || undefined,
+          entitiesChanged: entitiesChanged || undefined,
+          oldEntities: entitiesChanged ? oldFn.entities : undefined,
+          newEntities: entitiesChanged ? newFn.entities : undefined,
+          fieldReferencesChanged: fieldReferencesChanged || undefined,
+        });
+      }
+    }
+  }
+
+  const hasChanges =
+    addedGroups.length > 0 ||
+    removedGroups.length > 0 ||
+    addedEntities.length > 0 ||
+    removedEntities.length > 0 ||
+    functions.length > 0;
+
+  return {
+    hasChanges,
+    addedGroups,
+    removedGroups,
+    addedEntities,
+    removedEntities,
+    functions,
+    newOntology,
+    newHash,
+  };
+}
+
+/**
+ * Format a diff for console output
+ */
+export function formatDiffForConsole(diff: OntologyDiff): string {
+  if (!diff.hasChanges) {
+    return "No changes detected.";
+  }
+
+  const lines: string[] = ["Ontology changes detected:", ""];
+
+  if (diff.addedGroups.length > 0) {
+    lines.push("Added access groups:");
+    for (const group of diff.addedGroups) {
+      lines.push(`  + ${group}`);
+    }
+    lines.push("");
+  }
+
+  if (diff.removedGroups.length > 0) {
+    lines.push("Removed access groups:");
+    for (const group of diff.removedGroups) {
+      lines.push(`  - ${group}`);
+    }
+    lines.push("");
+  }
+
+  if (diff.addedEntities.length > 0) {
+    lines.push("Added entities:");
+    for (const entity of diff.addedEntities) {
+      lines.push(`  + ${entity}`);
+    }
+    lines.push("");
+  }
+
+  if (diff.removedEntities.length > 0) {
+    lines.push("Removed entities:");
+    for (const entity of diff.removedEntities) {
+      lines.push(`  - ${entity}`);
+    }
+    lines.push("");
+  }
+
+  if (diff.functions.length > 0) {
+    lines.push("Function changes:");
+    for (const fn of diff.functions) {
+      if (fn.type === "added") {
+        lines.push(`  + ${fn.name}`);
+        lines.push(`    Access: [${fn.newAccess?.join(", ")}]`);
+        if (fn.newEntities && fn.newEntities.length > 0) {
+          lines.push(`    Entities: [${fn.newEntities.join(", ")}]`);
+        }
+      } else if (fn.type === "removed") {
+        lines.push(`  - ${fn.name}`);
+      } else {
+        lines.push(`  ~ ${fn.name}`);
+        if (fn.oldAccess && fn.newAccess) {
+          lines.push(
+            `    Access: [${fn.oldAccess.join(", ")}] -> [${fn.newAccess.join(", ")}]`
+          );
+        }
+        if (fn.oldEntities && fn.newEntities) {
+          lines.push(
+            `    Entities: [${fn.oldEntities.join(", ")}] -> [${fn.newEntities.join(", ")}]`
+          );
+        }
+        if (fn.inputsChanged) {
+          lines.push(`    Inputs: schema changed`);
+        }
+        if (fn.outputsChanged) {
+          lines.push(`    Outputs: schema changed`);
+        }
+        if (fn.fieldReferencesChanged) {
+          lines.push(`    Field references: changed`);
+        }
+      }
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/lockfile/hasher.ts

@@ -0,0 +1,175 @@
+import { createHash } from "crypto";
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import type { OntologyConfig } from "../config/types.js";
+import { getFieldFromMetadata } from "../config/categorical.js";
+import type {
+  OntologySnapshot,
+  FunctionShape,
+  FieldReference,
+} from "./types.js";
+
+/**
+ * Recursively extract fieldFrom references from a Zod schema
+ */
+function extractFieldReferences(
+  schema: z.ZodType<unknown>,
+  path: string = ""
+): FieldReference[] {
+  const results: FieldReference[] = [];
+
+  // Check if this schema has fieldFrom metadata
+  const metadata = getFieldFromMetadata(schema);
+  if (metadata) {
+    results.push({
+      path: path || "(root)",
+      functionName: metadata.functionName,
+    });
+  }
+
+  // Handle ZodObject - recurse into properties
+  if (schema instanceof z.ZodObject) {
+    const shape = schema.shape;
+    for (const [key, value] of Object.entries(shape)) {
+      const fieldPath = path ? `${path}.${key}` : key;
+      results.push(
+        ...extractFieldReferences(value as z.ZodType<unknown>, fieldPath)
+      );
+    }
+  }
+
+  // Handle ZodOptional - unwrap
+  if (schema instanceof z.ZodOptional) {
+    results.push(...extractFieldReferences(schema.unwrap(), path));
+  }
+
+  // Handle ZodNullable - unwrap
+  if (schema instanceof z.ZodNullable) {
+    results.push(...extractFieldReferences(schema.unwrap(), path));
+  }
+
+  // Handle ZodArray - recurse into element
+  if (schema instanceof z.ZodArray) {
+    results.push(...extractFieldReferences(schema.element, `${path}[]`));
+  }
+
+  // Handle ZodDefault - unwrap
+  if (schema instanceof z.ZodDefault) {
+    results.push(...extractFieldReferences(schema._def.innerType, path));
+  }
+
+  return results;
+}
+
+/**
+ * Extract the ontology snapshot from an OntologyConfig.
+ * This extracts ONLY the security-relevant parts:
+ * - Function names
+ * - Access lists
+ * - Input schemas
+ * - Output schemas
+ * - Descriptions
+ * - Entities
+ * - Field references (fieldFrom)
+ *
+ * It DOES NOT include:
+ * - Resolver paths (so resolver code can change freely)
+ * - Environment configs
+ * - Auth function
+ */
+export function extractOntology(config: OntologyConfig): OntologySnapshot {
+  const functions: Record<string, FunctionShape> = {};
+
+  for (const [name, fn] of Object.entries(config.functions)) {
+    // Convert Zod schema to JSON Schema for hashing
+    // This ensures we're comparing the shape, not the Zod instance
+    let inputsSchema: Record<string, unknown>;
+    try {
+      inputsSchema = zodToJsonSchema(fn.inputs, {
+        // Remove $schema to make hashing more stable
+        $refStrategy: "none",
+      }) as Record<string, unknown>;
+      // Remove $schema key if present
+      delete inputsSchema.$schema;
+    } catch {
+      // If zodToJsonSchema fails, use a placeholder
+      inputsSchema = { type: "unknown" };
+    }
+
+    // Convert outputs schema if present
+    let outputsSchema: Record<string, unknown> | undefined;
+    if (fn.outputs) {
+      try {
+        outputsSchema = zodToJsonSchema(fn.outputs, {
+          $refStrategy: "none",
+        }) as Record<string, unknown>;
+        delete outputsSchema.$schema;
+      } catch {
+        outputsSchema = { type: "unknown" };
+      }
+    }
+
+    // Extract field references
+    const fieldReferences = extractFieldReferences(fn.inputs);
+
+    functions[name] = {
+      description: fn.description,
+      // Sort access groups for consistent hashing
+      access: [...fn.access].sort(),
+      // Sort entities for consistent hashing
+      entities: [...fn.entities].sort(),
+      inputsSchema,
+      outputsSchema,
+      fieldReferences:
+        fieldReferences.length > 0 ? fieldReferences : undefined,
+    };
+  }
+
+  return {
+    name: config.name,
+    // Sort access groups for consistent hashing
+    accessGroups: Object.keys(config.accessGroups).sort(),
+    // Sort entities for consistent hashing
+    entities: config.entities
+      ? Object.keys(config.entities).sort()
+      : undefined,
+    functions,
+  };
+}
+
+/**
+ * Create a deterministic hash of an ontology snapshot.
+ * Uses SHA256 and returns a 16-character hex string.
+ */
+export function hashOntology(ontology: OntologySnapshot): string {
+  // Sort all keys at all levels for deterministic hashing
+  const normalized = JSON.stringify(ontology, (_, value) => {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      // Sort object keys
+      return Object.keys(value)
+        .sort()
+        .reduce(
+          (sorted, key) => {
+            sorted[key] = value[key];
+            return sorted;
+          },
+          {} as Record<string, unknown>
+        );
+    }
+    return value;
+  });
+
+  return createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+}
+
+/**
+ * Extract ontology snapshot and compute hash in one step
+ */
+export function computeOntologyHash(config: OntologyConfig): {
+  ontology: OntologySnapshot;
+  hash: string;
+} {
+  const ontology = extractOntology(config);
+  const hash = hashOntology(ontology);
+  return { ontology, hash };
+}