ont-run 0.0.1

package/src/lockfile/index.ts

@@ -0,0 +1,159 @@
+import { readFile, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+import type { Lockfile, OntologySnapshot } from "./types.js";
+
+export { extractOntology, hashOntology, computeOntologyHash } from "./hasher.js";
+export { diffOntology, formatDiffForConsole } from "./differ.js";
+export type {
+  Lockfile,
+  OntologySnapshot,
+  OntologyDiff,
+  FunctionChange,
+  FunctionShape,
+} from "./types.js";
+
+const LOCKFILE_NAME = "ont.lock";
+const LOCKFILE_VERSION = 1;
+
+/**
+ * Get the lockfile path for a given config directory
+ */
+export function getLockfilePath(configDir: string): string {
+  return join(configDir, LOCKFILE_NAME);
+}
+
+/**
+ * Check if a lockfile exists
+ */
+export function lockfileExists(configDir: string): boolean {
+  return existsSync(getLockfilePath(configDir));
+}
+
+/**
+ * Read the lockfile from disk
+ * @returns The lockfile contents, or null if it doesn't exist
+ */
+export async function readLockfile(configDir: string): Promise<Lockfile | null> {
+  const path = getLockfilePath(configDir);
+
+  if (!existsSync(path)) {
+    return null;
+  }
+
+  try {
+    const content = await readFile(path, "utf-8");
+    const lockfile = JSON.parse(content) as Lockfile;
+
+    // Validate version
+    if (lockfile.version !== LOCKFILE_VERSION) {
+      throw new Error(
+        `Lockfile version mismatch. Expected ${LOCKFILE_VERSION}, got ${lockfile.version}`
+      );
+    }
+
+    return lockfile;
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`Failed to parse lockfile: ${error.message}`);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Write a lockfile to disk
+ */
+export async function writeLockfile(
+  configDir: string,
+  ontology: OntologySnapshot,
+  hash: string
+): Promise<void> {
+  const lockfile: Lockfile = {
+    version: LOCKFILE_VERSION,
+    hash,
+    approvedAt: new Date().toISOString(),
+    ontology,
+  };
+
+  const path = getLockfilePath(configDir);
+  const content = JSON.stringify(lockfile, null, 2);
+
+  await writeFile(path, content, "utf-8");
+}
+
+/**
+ * Check if the current ontology matches the lockfile
+ * @returns { match: true } if hashes match, or { match: false, lockfile, currentHash } if not
+ */
+export async function checkLockfile(
+  configDir: string,
+  currentHash: string
+): Promise<
+  | { match: true; lockfile: Lockfile }
+  | { match: false; lockfile: Lockfile | null; currentHash: string }
+> {
+  const lockfile = await readLockfile(configDir);
+
+  if (!lockfile) {
+    return { match: false, lockfile: null, currentHash };
+  }
+
+  if (lockfile.hash === currentHash) {
+    return { match: true, lockfile };
+  }
+
+  return { match: false, lockfile, currentHash };
+}
+
+/**
+ * Result of lockfile validation
+ */
+export interface LockfileValidationResult {
+  /** Status of the lockfile check */
+  status: "valid" | "missing" | "mismatch";
+  /** The diff if there are changes (only present for 'mismatch' status) */
+  diff?: import("./types.js").OntologyDiff;
+  /** Human-readable message */
+  message: string;
+}
+
+/**
+ * Validate the lockfile against the current ontology.
+ * This is the main entry point for library use.
+ *
+ * @param configDir - Directory containing the ontology.config.ts
+ * @param currentOntology - The current ontology snapshot
+ * @param currentHash - The current ontology hash
+ */
+export async function validateLockfile(
+  configDir: string,
+  currentOntology: OntologySnapshot,
+  currentHash: string
+): Promise<LockfileValidationResult> {
+  const { diffOntology } = await import("./differ.js");
+
+  if (!lockfileExists(configDir)) {
+    return {
+      status: "missing",
+      message: "No ont.lock file found. Run `bun run review` to approve the initial ontology.",
+    };
+  }
+
+  const lockfile = await readLockfile(configDir);
+  const oldOntology = lockfile?.ontology || null;
+  const diff = diffOntology(oldOntology, currentOntology);
+
+  if (!diff.hasChanges) {
+    return {
+      status: "valid",
+      message: "Lockfile is up to date.",
+    };
+  }
+
+  return {
+    status: "mismatch",
+    diff,
+    message: "Ontology has changed since last review. Run `bun run review` to approve changes.",
+  };
+}

package/src/lockfile/types.ts

@@ -0,0 +1,95 @@
+/**
+ * A field that references another function for its options
+ */
+export interface FieldReference {
+  /** Path to the field in the schema, e.g., "status" or "filters.country" */
+  path: string;
+  /** Name of the function that provides options for this field */
+  functionName: string;
+}
+
+/**
+ * Snapshot of a function's shape (what matters for security review)
+ */
+export interface FunctionShape {
+  /** Description of the function */
+  description: string;
+  /** Sorted list of access groups */
+  access: string[];
+  /** Sorted list of entities this function relates to */
+  entities: string[];
+  /** JSON Schema representation of the input schema */
+  inputsSchema: Record<string, unknown>;
+  /** JSON Schema representation of the output schema */
+  outputsSchema?: Record<string, unknown>;
+  /** Fields that reference other functions for their options */
+  fieldReferences?: FieldReference[];
+}
+
+/**
+ * Complete snapshot of the ontology
+ */
+export interface OntologySnapshot {
+  /** Name of the ontology */
+  name: string;
+  /** Sorted list of access group names */
+  accessGroups: string[];
+  /** Sorted list of entity names */
+  entities?: string[];
+  /** Function shapes keyed by name */
+  functions: Record<string, FunctionShape>;
+}
+
+/**
+ * The ont.lock file structure
+ */
+export interface Lockfile {
+  /** Lockfile format version */
+  version: number;
+  /** SHA256 hash of the ontology */
+  hash: string;
+  /** When this was approved */
+  approvedAt: string;
+  /** The full ontology snapshot */
+  ontology: OntologySnapshot;
+}
+
+/**
+ * A single change in a function
+ */
+export interface FunctionChange {
+  name: string;
+  type: "added" | "removed" | "modified";
+  oldAccess?: string[];
+  newAccess?: string[];
+  oldDescription?: string;
+  newDescription?: string;
+  inputsChanged?: boolean;
+  outputsChanged?: boolean;
+  entitiesChanged?: boolean;
+  oldEntities?: string[];
+  newEntities?: string[];
+  fieldReferencesChanged?: boolean;
+}
+
+/**
+ * Diff between old and new ontology
+ */
+export interface OntologyDiff {
+  /** Whether there are any changes */
+  hasChanges: boolean;
+  /** Added access groups */
+  addedGroups: string[];
+  /** Removed access groups */
+  removedGroups: string[];
+  /** Added entities */
+  addedEntities: string[];
+  /** Removed entities */
+  removedEntities: string[];
+  /** Function changes */
+  functions: FunctionChange[];
+  /** The new ontology (for writing to lockfile on approve) */
+  newOntology: OntologySnapshot;
+  /** The new hash */
+  newHash: string;
+}

package/src/runtime/index.ts

@@ -0,0 +1,114 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyHono = { fetch: (request: Request, ...args: any[]) => Response | Promise<Response> };
+
+/**
+ * Check if we're running in Bun
+ */
+export function isBun(): boolean {
+  return typeof globalThis.Bun !== "undefined";
+}
+
+/**
+ * Check if we're running in Node.js
+ */
+export function isNode(): boolean {
+  return (
+    typeof process !== "undefined" &&
+    process.versions != null &&
+    process.versions.node != null &&
+    !isBun()
+  );
+}
+
+/**
+ * Get the current runtime name
+ */
+export function getRuntime(): "bun" | "node" | "unknown" {
+  if (isBun()) return "bun";
+  if (isNode()) return "node";
+  return "unknown";
+}
+
+export interface ServerHandle {
+  port: number;
+  stop: () => void | Promise<void>;
+}
+
+/**
+ * Start an HTTP server using the appropriate runtime
+ */
+export async function serve(
+  app: AnyHono,
+  port: number
+): Promise<ServerHandle> {
+  if (isBun()) {
+    const server = Bun.serve({
+      port,
+      fetch: app.fetch,
+      // Disable idle timeout for SSE/streaming connections
+      idleTimeout: 0,
+    });
+    return {
+      port: server.port ?? port,
+      stop: () => server.stop(),
+    };
+  }
+
+  // Node.js
+  const { serve: nodeServe } = await import("@hono/node-server");
+
+  return new Promise((resolve) => {
+    const server = nodeServe({
+      fetch: app.fetch,
+      port,
+    }, (info) => {
+      resolve({
+        port: info.port,
+        stop: () => {
+          server.close();
+        },
+      });
+    });
+  });
+}
+
+/**
+ * Find an available port starting from the given port
+ */
+export async function findAvailablePort(startPort: number = 3456): Promise<number> {
+  if (isBun()) {
+    for (let port = startPort; port < startPort + 100; port++) {
+      try {
+        const server = Bun.serve({
+          port,
+          fetch: () => new Response("test"),
+        });
+        server.stop();
+        return port;
+      } catch {
+        // Port in use, try next
+      }
+    }
+    throw new Error("Could not find available port");
+  }
+
+  // Node.js - use net module to check port availability
+  const net = await import("net");
+
+  return new Promise((resolve, reject) => {
+    const tryPort = (port: number) => {
+      if (port >= startPort + 100) {
+        reject(new Error("Could not find available port"));
+        return;
+      }
+
+      const server = net.createServer();
+      server.listen(port, () => {
+        server.close(() => resolve(port));
+      });
+      server.on("error", () => tryPort(port + 1));
+    };
+
+    tryPort(startPort);
+  });
+}

package/src/server/api/index.ts

@@ -0,0 +1,92 @@
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import consola from "consola";
+import type { OntologyConfig } from "../../config/types.js";
+import {
+  createAuthMiddleware,
+  createContextMiddleware,
+  errorHandler,
+  type OntologyVariables,
+} from "./middleware.js";
+import { createApiRoutes, getFunctionsInfo } from "./router.js";
+import { findMissingResolvers } from "../resolver.js";
+
+export interface ApiServerOptions {
+  /** The ontology configuration */
+  config: OntologyConfig;
+  /** Directory containing the ontology.config.ts (for resolving resolver paths) */
+  configDir: string;
+  /** Environment to use (e.g., 'dev', 'prod') */
+  env: string;
+  /** Enable CORS (default: true) */
+  cors?: boolean;
+}
+
+/**
+ * Create the Hono API app from an OntologyConfig
+ */
+export function createApiApp(options: ApiServerOptions): Hono<{ Variables: OntologyVariables }> {
+  const { config, configDir, env, cors: enableCors = true } = options;
+
+  // Get environment config
+  const envConfig = config.environments[env];
+  if (!envConfig) {
+    throw new Error(
+      `Unknown environment "${env}". Available: ${Object.keys(config.environments).join(", ")}`
+    );
+  }
+
+  // Check for missing resolvers
+  const missingResolvers = findMissingResolvers(config, configDir);
+  if (missingResolvers.length > 0) {
+    consola.warn(`Missing resolvers (${missingResolvers.length}):`);
+    for (const resolver of missingResolvers) {
+      consola.warn(`  - ${resolver}`);
+    }
+  }
+
+  const app = new Hono<{ Variables: OntologyVariables }>();
+
+  // Global middleware
+  if (enableCors) {
+    app.use("*", cors());
+  }
+  app.use("*", errorHandler());
+  app.use("*", createAuthMiddleware(config));
+  app.use("*", createContextMiddleware(env, envConfig));
+
+  // Health check endpoint (no auth required, override for this route)
+  app.get("/health", (c) => {
+    return c.json({
+      status: "ok",
+      name: config.name,
+      env,
+    });
+  });
+
+  // Introspection endpoint - list available functions
+  app.get("/api", (c) => {
+    const accessGroups = c.get("accessGroups") || [];
+    const allFunctions = getFunctionsInfo(config);
+
+    // Filter to only show functions the user has access to
+    const accessibleFunctions = allFunctions.filter((fn) =>
+      fn.access.some((group) => accessGroups.includes(group))
+    );
+
+    return c.json({
+      name: config.name,
+      env,
+      accessGroups,
+      functions: accessibleFunctions,
+    });
+  });
+
+  // Mount function routes under /api
+  const apiRoutes = createApiRoutes(config, configDir);
+  app.route("/api", apiRoutes);
+
+  return app;
+}
+
+export { getFunctionsInfo } from "./router.js";

package/src/server/api/middleware.ts

@@ -0,0 +1,118 @@
+import { createMiddleware } from "hono/factory";
+import type { Context, Next } from "hono";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import type { OntologyConfig, ResolverContext, EnvironmentConfig } from "../../config/types.js";
+import { createLogger } from "../resolver.js";
+
+/**
+ * Context variables added by middleware
+ */
+export interface OntologyVariables {
+  resolverContext: ResolverContext;
+  accessGroups: string[];
+}
+
+/**
+ * Create auth middleware that calls the user's auth function
+ * and sets the access groups on the context
+ */
+export function createAuthMiddleware(config: OntologyConfig) {
+  return createMiddleware<{ Variables: OntologyVariables }>(
+    async (c: Context<{ Variables: OntologyVariables }>, next: Next) => {
+      try {
+        // Call user's auth function
+        const accessGroups = await config.auth(c.req.raw);
+        c.set("accessGroups", accessGroups);
+        await next();
+      } catch (error) {
+        return c.json(
+          {
+            error: "Authentication failed",
+            message: error instanceof Error ? error.message : "Unknown error",
+          },
+          401
+        );
+      }
+    }
+  );
+}
+
+/**
+ * Create context middleware that builds the ResolverContext
+ */
+export function createContextMiddleware(
+  env: string,
+  envConfig: EnvironmentConfig
+) {
+  const logger = createLogger(envConfig.debug);
+
+  return createMiddleware<{ Variables: OntologyVariables }>(
+    async (c: Context<{ Variables: OntologyVariables }>, next: Next) => {
+      const accessGroups = c.get("accessGroups") || [];
+
+      const resolverContext: ResolverContext = {
+        env,
+        envConfig,
+        logger,
+        accessGroups,
+      };
+
+      c.set("resolverContext", resolverContext);
+      await next();
+    }
+  );
+}
+
+/**
+ * Create access control middleware for a specific function
+ */
+export function createAccessControlMiddleware(requiredAccess: string[]) {
+  return createMiddleware<{ Variables: OntologyVariables }>(
+    async (c: Context<{ Variables: OntologyVariables }>, next: Next) => {
+      const accessGroups = c.get("accessGroups") || [];
+
+      // Check if user has at least one of the required access groups
+      const hasAccess = requiredAccess.some((group) =>
+        accessGroups.includes(group)
+      );
+
+      if (!hasAccess) {
+        return c.json(
+          {
+            error: "Access denied",
+            message: `This function requires one of: ${requiredAccess.join(", ")}`,
+            yourGroups: accessGroups,
+          },
+          403
+        );
+      }
+
+      await next();
+    }
+  );
+}
+
+/**
+ * Error handling middleware
+ */
+export function errorHandler() {
+  return createMiddleware(async (c: Context, next: Next) => {
+    try {
+      await next();
+    } catch (error) {
+      console.error("Request error:", error);
+
+      const status = (error as { status?: number }).status || 500;
+      const message =
+        error instanceof Error ? error.message : "Internal server error";
+
+      return c.json(
+        {
+          error: "Request failed",
+          message,
+        },
+        status as ContentfulStatusCode
+      );
+    }
+  });
+}

package/src/server/api/router.ts

@@ -0,0 +1,102 @@
+import { Hono } from "hono";
+import type { OntologyConfig, FunctionDefinition } from "../../config/types.js";
+import { loadResolver } from "../resolver.js";
+import {
+  createAccessControlMiddleware,
+  type OntologyVariables,
+} from "./middleware.js";
+
+/**
+ * Create API routes from function definitions
+ */
+export function createApiRoutes(
+  config: OntologyConfig,
+  configDir: string
+): Hono<{ Variables: OntologyVariables }> {
+  const router = new Hono<{ Variables: OntologyVariables }>();
+
+  // Create a route for each function
+  for (const [name, fn] of Object.entries(config.functions)) {
+    const path = `/${name}`;
+
+    router.post(
+      path,
+      // Access control for this specific function
+      createAccessControlMiddleware(fn.access),
+      // Handler
+      async (c) => {
+        const resolverContext = c.get("resolverContext");
+
+        // Parse and validate input
+        let args: unknown;
+        try {
+          const body = await c.req.json();
+          const parsed = fn.inputs.safeParse(body);
+
+          if (!parsed.success) {
+            return c.json(
+              {
+                error: "Validation failed",
+                issues: parsed.error.issues,
+              },
+              400
+            );
+          }
+
+          args = parsed.data;
+        } catch {
+          // No body or invalid JSON - try with empty object
+          const parsed = fn.inputs.safeParse({});
+          if (!parsed.success) {
+            return c.json(
+              {
+                error: "Validation failed",
+                message: "Request body is required",
+                issues: parsed.error.issues,
+              },
+              400
+            );
+          }
+          args = parsed.data;
+        }
+
+        // Load and execute resolver
+        try {
+          const resolver = await loadResolver(fn.resolver, configDir);
+          const result = await resolver(resolverContext, args);
+          return c.json(result);
+        } catch (error) {
+          console.error(`Error in resolver ${name}:`, error);
+          return c.json(
+            {
+              error: "Resolver failed",
+              message: error instanceof Error ? error.message : "Unknown error",
+            },
+            500
+          );
+        }
+      }
+    );
+  }
+
+  return router;
+}
+
+/**
+ * Get info about all available functions (for introspection)
+ */
+export function getFunctionsInfo(
+  config: OntologyConfig
+): Array<{
+  name: string;
+  description: string;
+  access: string[];
+  path: string;
+}> {
+  return Object.entries(config.functions).map(([name, fn]) => ({
+    name,
+    description: fn.description,
+    access: fn.access,
+    path: `/api/${name}`,
+  }));
+}