ont-run 0.0.1

package/src/cli/commands/review.ts

@@ -0,0 +1,126 @@
+import { defineCommand } from "citty";
+import consola from "consola";
+import { loadConfig } from "../utils/config-loader.js";
+import {
+  computeOntologyHash,
+  readLockfile,
+  diffOntology,
+  formatDiffForConsole,
+  writeLockfile,
+} from "../../lockfile/index.js";
+import { startBrowserServer } from "../../browser/server.js";
+
+export const reviewCommand = defineCommand({
+  meta: {
+    name: "review",
+    description: "Review and approve ontology changes",
+  },
+  args: {
+    "auto-approve": {
+      type: "boolean",
+      description: "Automatically approve changes (for CI/scripts)",
+      default: false,
+    },
+    "print-only": {
+      type: "boolean",
+      description: "Print diff and exit without prompting",
+      default: false,
+    },
+    cloud: {
+      type: "boolean",
+      description: "Sync with ont Cloud for team approvals",
+      default: false,
+    },
+  },
+  async run({ args }) {
+    try {
+      // Check for cloud mode
+      const cloudToken = process.env.ONT_CLOUD_TOKEN;
+      if (args.cloud || cloudToken) {
+        consola.info("");
+        consola.box(
+          "ont Cloud coming soon!\n\n" +
+            "Team approvals, audit trails, and compliance reporting.\n\n" +
+            "Sign up for early access: https://ont.dev/cloud"
+        );
+        process.exit(0);
+      }
+
+      // Load config
+      consola.info("Loading ontology config...");
+      const { config, configDir } = await loadConfig();
+
+      // Compute current ontology snapshot
+      const { ontology: newOntology, hash: newHash } = computeOntologyHash(config);
+
+      // Load existing lockfile
+      const lockfile = await readLockfile(configDir);
+      const oldOntology = lockfile?.ontology || null;
+
+      // Compute diff
+      const diff = diffOntology(oldOntology, newOntology);
+
+      // Handle print-only mode
+      if (args["print-only"]) {
+        if (diff.hasChanges) {
+          console.log("\n" + formatDiffForConsole(diff) + "\n");
+          process.exit(1);
+        } else {
+          consola.success("No ontology changes detected.");
+          process.exit(0);
+        }
+      }
+
+      // Handle auto-approve mode
+      if (args["auto-approve"]) {
+        if (diff.hasChanges) {
+          console.log("\n" + formatDiffForConsole(diff) + "\n");
+          consola.info("Auto-approving changes...");
+          await writeLockfile(configDir, newOntology, newHash);
+          consola.success("Changes approved. Lockfile updated.");
+        } else {
+          consola.success("No ontology changes detected.");
+          if (!lockfile) {
+            consola.info("Writing initial lockfile...");
+            await writeLockfile(configDir, newOntology, newHash);
+            consola.success("Created ont.lock");
+          }
+        }
+        return;
+      }
+
+      // Handle initial lockfile creation (no previous state)
+      if (!lockfile && !diff.hasChanges) {
+        consola.info("Writing initial lockfile...");
+        await writeLockfile(configDir, newOntology, newHash);
+        consola.success("Created ont.lock");
+      }
+
+      // Print diff summary to console if there are changes
+      if (diff.hasChanges) {
+        console.log("\n" + formatDiffForConsole(diff) + "\n");
+      }
+
+      // Start unified browser/review UI
+      consola.info(diff.hasChanges ? "Starting review UI..." : "Starting ontology browser...");
+      const result = await startBrowserServer({
+        config,
+        diff: diff.hasChanges ? diff : null,
+        configDir,
+      });
+
+      if (diff.hasChanges) {
+        if (result.approved) {
+          consola.success("Changes approved. Lockfile updated.");
+          process.exit(0);
+        } else {
+          consola.warn("Changes rejected.");
+          process.exit(1);
+        }
+      }
+    } catch (error) {
+      consola.error(error instanceof Error ? error.message : "Unknown error");
+      process.exit(1);
+    }
+  },
+});

package/src/cli/index.ts

@@ -0,0 +1,19 @@
+import { defineCommand, runMain } from "citty";
+import { initCommand } from "./commands/init.js";
+import { reviewCommand } from "./commands/review.js";
+
+const main = defineCommand({
+  meta: {
+    name: "ont",
+    description: "Ontology - Ontology-first backends with human-approved AI access & edits",
+    version: "0.1.0",
+  },
+  subCommands: {
+    init: initCommand,
+    review: reviewCommand,
+  },
+});
+
+export function run() {
+  runMain(main);
+}

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

@@ -0,0 +1,78 @@
+import { existsSync } from "fs";
+import { join, dirname, resolve } from "path";
+import type { OntologyConfig } from "../../config/types.js";
+
+const CONFIG_FILENAMES = ["ontology.config.ts", "ontology.config.js"];
+
+/**
+ * Find the ontology config file in the given directory or its parents
+ */
+export function findConfigFile(startDir: string = process.cwd()): string | null {
+  let currentDir = resolve(startDir);
+
+  while (true) {
+    for (const filename of CONFIG_FILENAMES) {
+      const configPath = join(currentDir, filename);
+      if (existsSync(configPath)) {
+        return configPath;
+      }
+    }
+
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      // Reached root
+      return null;
+    }
+    currentDir = parentDir;
+  }
+}
+
+/**
+ * Load the ontology config from a file
+ */
+export async function loadConfig(configPath?: string): Promise<{
+  config: OntologyConfig;
+  configDir: string;
+  configPath: string;
+}> {
+  // Find config file if not provided
+  const resolvedPath = configPath || findConfigFile();
+
+  if (!resolvedPath) {
+    throw new Error(
+      "Could not find ontology.config.ts in current directory or any parent directory.\n" +
+        "Run `ont init` to create a new project."
+    );
+  }
+
+  if (!existsSync(resolvedPath)) {
+    throw new Error(`Config file not found: ${resolvedPath}`);
+  }
+
+  const configDir = dirname(resolvedPath);
+
+  try {
+    // Dynamic import the config
+    const module = await import(resolvedPath);
+    const config = module.default as OntologyConfig;
+
+    if (!config || typeof config !== "object") {
+      throw new Error(
+        "Config file must export a default object created with defineOntology()"
+      );
+    }
+
+    if (!config.name || !config.functions) {
+      throw new Error(
+        "Invalid config: missing required fields (name, functions)"
+      );
+    }
+
+    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}`);
+    }
+    throw error;
+  }
+}

package/src/config/categorical.ts

@@ -0,0 +1,101 @@
+import { z } from "zod";
+
+/**
+ * Symbol for storing fieldFrom metadata on Zod schemas
+ */
+export const FIELD_FROM_METADATA = Symbol.for("ont:fieldFrom");
+
+/**
+ * Metadata stored on fieldFrom Zod schemas
+ */
+export interface FieldFromMetadata {
+  /** Name of the function that provides options for this field */
+  functionName: string;
+}
+
+/**
+ * Type for a Zod string with fieldFrom metadata
+ */
+export type FieldFromString = z.ZodString & {
+  [FIELD_FROM_METADATA]: FieldFromMetadata;
+};
+
+/**
+ * Create a string field that gets its options from another function.
+ *
+ * The referenced function should return `{ value: string, label: string }[]`.
+ * - If the function has empty inputs `z.object({})`, it's treated as **bulk** (all options fetched at once)
+ * - If the function has a `query` input, it's treated as **autocomplete** (options searched)
+ *
+ * @param functionName - Name of the function that provides options
+ *
+ * @example
+ * ```ts
+ * defineOntology({
+ *   functions: {
+ *     // Bulk options source (empty inputs)
+ *     getUserStatuses: {
+ *       description: 'Get available user statuses',
+ *       access: ['admin'],
+ *       entities: [],
+ *       inputs: z.object({}),
+ *       outputs: z.array(z.object({ value: z.string(), label: z.string() })),
+ *       resolver: './resolvers/options/userStatuses.ts',
+ *     },
+ *
+ *     // Autocomplete source (has query input)
+ *     searchTeams: {
+ *       description: 'Search for teams',
+ *       access: ['admin'],
+ *       entities: [],
+ *       inputs: z.object({ query: z.string() }),
+ *       outputs: z.array(z.object({ value: z.string(), label: z.string() })),
+ *       resolver: './resolvers/options/searchTeams.ts',
+ *     },
+ *
+ *     // Function using fieldFrom
+ *     createUser: {
+ *       description: 'Create a user',
+ *       access: ['admin'],
+ *       entities: ['User'],
+ *       inputs: z.object({
+ *         name: z.string(),
+ *         status: fieldFrom('getUserStatuses'),
+ *         team: fieldFrom('searchTeams'),
+ *       }),
+ *       resolver: './resolvers/createUser.ts',
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export function fieldFrom(functionName: string): FieldFromString {
+  const schema = z.string() as FieldFromString;
+  schema[FIELD_FROM_METADATA] = { functionName };
+  return schema;
+}
+
+/**
+ * Check if a Zod schema has fieldFrom metadata
+ */
+export function hasFieldFromMetadata(
+  schema: unknown
+): schema is FieldFromString {
+  return (
+    schema !== null &&
+    typeof schema === "object" &&
+    FIELD_FROM_METADATA in schema
+  );
+}
+
+/**
+ * Extract fieldFrom metadata from a Zod schema
+ */
+export function getFieldFromMetadata(
+  schema: unknown
+): FieldFromMetadata | null {
+  if (hasFieldFromMetadata(schema)) {
+    return schema[FIELD_FROM_METADATA];
+  }
+  return null;
+}

package/src/config/define.ts

@@ -0,0 +1,78 @@
+import {
+  OntologyConfigSchema,
+  validateAccessGroups,
+  validateEntityReferences,
+  validateFieldFromReferences,
+} from "./schema.js";
+import type {
+  OntologyConfig,
+  FunctionDefinition,
+  AccessGroupConfig,
+  EnvironmentConfig,
+  EntityDefinition,
+  AuthFunction,
+} from "./types.js";
+
+/**
+ * Define an Ontology configuration with full type inference.
+ *
+ * @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) => {
+ *     const token = req.headers.get('Authorization');
+ *     return token ? ['admin'] : ['public'];
+ *   },
+ *   accessGroups: {
+ *     public: { description: 'Unauthenticated users' },
+ *     admin: { description: 'Administrators' },
+ *   },
+ *   entities: {
+ *     User: { description: 'A user account' },
+ *   },
+ *   functions: {
+ *     getUser: {
+ *       description: 'Get a user by ID',
+ *       access: ['public', 'admin'],
+ *       entities: ['User'],
+ *       inputs: z.object({ id: z.string() }),
+ *       resolver: './resolvers/getUser.ts',
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function defineOntology<
+  TGroups extends string,
+  TEntities extends string,
+  TFunctions extends Record<string, FunctionDefinition<TGroups, TEntities>>,
+>(config: {
+  name: string;
+  environments: Record<string, EnvironmentConfig>;
+  auth: AuthFunction;
+  accessGroups: Record<TGroups, AccessGroupConfig>;
+  entities?: Record<TEntities, EntityDefinition>;
+  functions: TFunctions;
+}): OntologyConfig<TGroups, TEntities, TFunctions> {
+  // Validate the config structure
+  const parsed = OntologyConfigSchema.parse(config);
+
+  // Validate that all access groups referenced in functions exist
+  validateAccessGroups(parsed);
+
+  // Validate that all entities referenced in functions exist
+  validateEntityReferences(parsed);
+
+  // Validate that all fieldFrom() references point to existing functions
+  validateFieldFromReferences(parsed);
+
+  return config as OntologyConfig<TGroups, TEntities, TFunctions>;
+}

package/src/config/index.ts

@@ -0,0 +1,23 @@
+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";

package/src/config/schema.ts

@@ -0,0 +1,196 @@
+import { z } from "zod";
+import { getFieldFromMetadata } from "./categorical.js";
+
+/**
+ * Schema for environment configuration
+ */
+export const EnvironmentConfigSchema = z
+  .object({
+    debug: z.boolean().optional(),
+  })
+  .passthrough();
+
+/**
+ * Schema for access group configuration
+ */
+export const AccessGroupConfigSchema = z.object({
+  description: z.string(),
+});
+
+/**
+ * Schema for entity definition
+ */
+export const EntityDefinitionSchema = z.object({
+  description: z.string(),
+});
+
+/**
+ * Check if a value is a Zod schema (duck typing to work across bundle boundaries)
+ */
+function isZodSchema(val: unknown): boolean {
+  return (
+    val !== null &&
+    typeof val === "object" &&
+    "_def" in val &&
+    "safeParse" in val &&
+    typeof (val as { safeParse: unknown }).safeParse === "function"
+  );
+}
+
+/**
+ * Schema for function definition
+ */
+export const FunctionDefinitionSchema = z.object({
+  description: z.string(),
+  access: z.array(z.string()).min(1),
+  entities: z.array(z.string()),
+  inputs: z.custom<z.ZodType>(isZodSchema, {
+    message: "inputs must be a Zod schema",
+  }),
+  outputs: z
+    .custom<z.ZodType>(isZodSchema, {
+      message: "outputs must be a Zod schema",
+    })
+    .optional(),
+  resolver: z.string(),
+});
+
+/**
+ * Schema for auth function
+ */
+export const AuthFunctionSchema = z
+  .function()
+  .args(z.custom<Request>())
+  .returns(z.union([z.array(z.string()), z.promise(z.array(z.string()))]));
+
+/**
+ * Schema for the full ontology configuration
+ */
+export const OntologyConfigSchema = z.object({
+  name: z.string().min(1),
+  environments: z.record(z.string(), EnvironmentConfigSchema),
+  auth: z.function(),
+  accessGroups: z.record(z.string(), AccessGroupConfigSchema),
+  entities: z.record(z.string(), EntityDefinitionSchema).optional(),
+  functions: z.record(z.string(), FunctionDefinitionSchema),
+});
+
+/**
+ * Validate that all function access groups exist in accessGroups
+ */
+export function validateAccessGroups(
+  config: z.infer<typeof OntologyConfigSchema>
+): void {
+  const validGroups = new Set(Object.keys(config.accessGroups));
+
+  for (const [fnName, fn] of Object.entries(config.functions)) {
+    for (const group of fn.access) {
+      if (!validGroups.has(group)) {
+        throw new Error(
+          `Function "${fnName}" references unknown access group "${group}". ` +
+            `Valid groups: ${[...validGroups].join(", ")}`
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Validate that all function entity references exist in entities
+ */
+export function validateEntityReferences(
+  config: z.infer<typeof OntologyConfigSchema>
+): void {
+  const validEntities = config.entities
+    ? new Set(Object.keys(config.entities))
+    : new Set<string>();
+
+  for (const [fnName, fn] of Object.entries(config.functions)) {
+    for (const entity of fn.entities) {
+      if (!validEntities.has(entity)) {
+        const validList =
+          validEntities.size > 0
+            ? [...validEntities].join(", ")
+            : "(none defined)";
+        throw new Error(
+          `Function "${fnName}" references unknown entity "${entity}". ` +
+            `Valid entities: ${validList}`
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Recursively extract fieldFrom references from a Zod schema
+ */
+function extractFieldFromRefs(
+  schema: z.ZodType<unknown>,
+  path: string = ""
+): Array<{ path: string; functionName: string }> {
+  const results: Array<{ path: string; functionName: string }> = [];
+
+  // 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(
+        ...extractFieldFromRefs(value as z.ZodType<unknown>, fieldPath)
+      );
+    }
+  }
+
+  // Handle ZodOptional - unwrap
+  if (schema instanceof z.ZodOptional) {
+    results.push(...extractFieldFromRefs(schema.unwrap(), path));
+  }
+
+  // Handle ZodNullable - unwrap
+  if (schema instanceof z.ZodNullable) {
+    results.push(...extractFieldFromRefs(schema.unwrap(), path));
+  }
+
+  // Handle ZodArray - recurse into element
+  if (schema instanceof z.ZodArray) {
+    results.push(...extractFieldFromRefs(schema.element, `${path}[]`));
+  }
+
+  // Handle ZodDefault - unwrap
+  if (schema instanceof z.ZodDefault) {
+    results.push(...extractFieldFromRefs(schema._def.innerType, path));
+  }
+
+  return results;
+}
+
+/**
+ * Validate that all fieldFrom() references point to existing functions
+ */
+export function validateFieldFromReferences(
+  config: z.infer<typeof OntologyConfigSchema>
+): void {
+  const validFunctions = new Set(Object.keys(config.functions));
+
+  for (const [fnName, fn] of Object.entries(config.functions)) {
+    const refs = extractFieldFromRefs(fn.inputs);
+
+    for (const ref of refs) {
+      if (!validFunctions.has(ref.functionName)) {
+        throw new Error(
+          `Function "${fnName}" field "${ref.path}" references unknown function "${ref.functionName}" via fieldFrom(). ` +
+            `Valid functions: ${[...validFunctions].join(", ")}`
+        );
+      }
+    }
+  }
+}