@aigne/afs 1.11.0-beta → 1.11.0-beta.10

package/dist/loader/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/loader/index.ts"],"sourcesContent":["/**\n * AFS Provider Dynamic Loader\n *\n * Provides utilities for dynamically loading AFS providers at runtime.\n *\n * @example\n * ```typescript\n * import { loadProvider, getProviderSchema } from \"@aigne/afs/loader\";\n *\n * // Load a provider with configuration\n * const fs = await loadProvider(\"@aigne/afs-fs\", {\n *   config: { localPath: \"./data\" },\n *   basePath: \"/path/to/config/dir\"\n * });\n *\n * // Get provider schema for validation\n * const schema = await getProviderSchema(\"@aigne/afs-fs\");\n * ```\n */\n\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport type { ZodType } from \"zod\";\nimport type { AFSModule, AFSModuleLoadParams } from \"../type.js\";\n\n// Re-export types for convenience\nexport type { AFSModuleLoadParams } from \"../type.js\";\n\n/**\n * Resolve a package specifier to an importable path.\n * If the specifier is a directory path (e.g. from npm install),\n * read its package.json to find the ESM entry point.\n * We must use the ESM (.mjs) entry, not CJS (.cjs), because\n * importing CJS from ESM wraps module.exports in an extra default layer\n * which breaks the expected export shape.\n */\nfunction resolveImportPath(specifier: string): string {\n  if (!specifier.startsWith(\"/\")) return specifier;\n\n  const pkgJsonPath = join(specifier, \"package.json\");\n  if (!existsSync(pkgJsonPath)) return specifier;\n\n  try {\n    const pkg = JSON.parse(readFileSync(pkgJsonPath, \"utf-8\"));\n    // Prefer ESM entry: exports[\".\"].import > module > main\n    const esmEntry = (typeof pkg.exports === \"object\" && pkg.exports[\".\"]?.import) || pkg.module;\n    if (esmEntry) return join(specifier, esmEntry);\n    // Fallback to main (may be CJS)\n    if (pkg.main) return join(specifier, pkg.main);\n  } catch {\n    // Fall through to use original specifier\n  }\n  return specifier;\n}\n\n/**\n * Dynamically load an AFS Provider from a package.\n *\n * @param packageName - Package name or subpath (e.g., \"@aigne/afs-fs\" or \"@aigne/afs-cloud/s3\")\n * @param options - Load options (optional)\n * @returns Provider instance\n *\n * @throws Error if package doesn't exist or doesn't export a valid AFS Provider\n *\n * @example\n * ```typescript\n * const fs = await loadProvider(\"@aigne/afs-fs\", {\n *   config: { localPath: \"./data\" },\n *   basePath: \"/path/to/config/dir\"\n * });\n * ```\n */\nexport async function loadProvider<T extends AFSModule = AFSModule>(\n  packageName: string,\n  options?: AFSModuleLoadParams,\n): Promise<T> {\n  // 1. Dynamic import the package\n  const importPath = resolveImportPath(packageName);\n  let module: Record<string, unknown>;\n  try {\n    module = (await import(importPath)) as Record<string, unknown>;\n  } catch (error) {\n    throw new Error(\n      `Failed to import package \"${packageName}\": ${error instanceof Error ? error.message : String(error)}`,\n    );\n  }\n\n  // 2. Get the default export\n  const ProviderClass = module.default as {\n    load?: (params: AFSModuleLoadParams) => Promise<T>;\n  };\n\n  if (!ProviderClass || typeof ProviderClass.load !== \"function\") {\n    throw new Error(\n      `Package \"${packageName}\" does not export a valid AFS Provider. ` +\n        `Expected default export with static load() method.`,\n    );\n  }\n\n  // 3. Call load() to create instance\n  return ProviderClass.load(options ?? {});\n}\n\n/**\n * Get the configuration schema for an AFS Provider without creating an instance.\n *\n * Useful for:\n * - Configuration validation\n * - Documentation generation\n * - IDE integration\n *\n * @param packageName - Package name or subpath\n * @returns Zod schema for the provider's configuration\n *\n * @throws Error if package doesn't export schema() method\n *\n * @example\n * ```typescript\n * const schema = await getProviderSchema(\"@aigne/afs-fs\");\n * const result = schema.safeParse(config);\n * if (!result.success) {\n *   console.error(result.error);\n * }\n * ```\n */\nexport async function getProviderSchema(packageName: string): Promise<ZodType<unknown>> {\n  // Dynamic import the package\n  const importPath = resolveImportPath(packageName);\n  let module: Record<string, unknown>;\n  try {\n    module = (await import(importPath)) as Record<string, unknown>;\n  } catch (error) {\n    throw new Error(\n      `Failed to import package \"${packageName}\": ${error instanceof Error ? error.message : String(error)}`,\n    );\n  }\n\n  const ProviderClass = module.default as {\n    schema?: () => ZodType<unknown>;\n  };\n\n  if (!ProviderClass || typeof ProviderClass.schema !== \"function\") {\n    throw new Error(`Package \"${packageName}\" does not export schema() method.`);\n  }\n\n  return ProviderClass.schema();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,SAAS,kBAAkB,WAA2B;AACpD,KAAI,CAAC,UAAU,WAAW,IAAI,CAAE,QAAO;CAEvC,MAAM,cAAc,KAAK,WAAW,eAAe;AACnD,KAAI,CAAC,WAAW,YAAY,CAAE,QAAO;AAErC,KAAI;EACF,MAAM,MAAM,KAAK,MAAM,aAAa,aAAa,QAAQ,CAAC;EAE1D,MAAM,WAAY,OAAO,IAAI,YAAY,YAAY,IAAI,QAAQ,MAAM,UAAW,IAAI;AACtF,MAAI,SAAU,QAAO,KAAK,WAAW,SAAS;AAE9C,MAAI,IAAI,KAAM,QAAO,KAAK,WAAW,IAAI,KAAK;SACxC;AAGR,QAAO;;;;;;;;;;;;;;;;;;;AAoBT,eAAsB,aACpB,aACA,SACY;CAEZ,MAAM,aAAa,kBAAkB,YAAY;CACjD,IAAI;AACJ,KAAI;AACF,WAAU,MAAM,OAAO;UAChB,OAAO;AACd,QAAM,IAAI,MACR,6BAA6B,YAAY,KAAK,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM,GACrG;;CAIH,MAAM,gBAAgB,OAAO;AAI7B,KAAI,CAAC,iBAAiB,OAAO,cAAc,SAAS,WAClD,OAAM,IAAI,MACR,YAAY,YAAY,4FAEzB;AAIH,QAAO,cAAc,KAAK,WAAW,EAAE,CAAC;;;;;;;;;;;;;;;;;;;;;;;;AAyB1C,eAAsB,kBAAkB,aAAgD;CAEtF,MAAM,aAAa,kBAAkB,YAAY;CACjD,IAAI;AACJ,KAAI;AACF,WAAU,MAAM,OAAO;UAChB,OAAO;AACd,QAAM,IAAI,MACR,6BAA6B,YAAY,KAAK,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM,GACrG;;CAGH,MAAM,gBAAgB,OAAO;AAI7B,KAAI,CAAC,iBAAiB,OAAO,cAAc,WAAW,WACpD,OAAM,IAAI,MAAM,YAAY,YAAY,oCAAoC;AAG9E,QAAO,cAAc,QAAQ"}

package/dist/meta/index.cjs

@@ -0,0 +1,4 @@
+const require_validation = require('./validation.cjs');
+const require_well_known_kinds = require('./well-known-kinds.cjs');
+const require_kind = require('./kind.cjs');
+const require_path = require('./path.cjs');

package/dist/meta/index.mjs

@@ -0,0 +1,6 @@
+import { combineValidationResults, validateNodes } from "./validation.mjs";
+import { WELL_KNOWN_KINDS, WELL_KNOWN_KINDS_MAP, afsDocument, afsExecutable, afsImage, afsLink, afsNode, commonMetaSchema, getWellKnownKind, isWellKnownKind } from "./well-known-kinds.mjs";
+import { KindError, createKindResolver, defaultKindResolver, defineKind, getInheritanceChain, resolveKindSchema } from "./kind.mjs";
+import { KINDS_SEGMENT, META_SEGMENT, getNodePathFromMetaPath, isKindsPath, isMetaPath, parseMetaPath } from "./path.mjs";
+
+export {  };

package/dist/meta/kind.cjs

@@ -0,0 +1,161 @@
+const require_utils_zod = require('../utils/zod.cjs');
+const require_validation = require('./validation.cjs');
+const require_well_known_kinds = require('./well-known-kinds.cjs');
+let zod_from_json_schema = require("zod-from-json-schema");
+
+//#region src/meta/kind.ts
+/**
+* Default kind resolver that only knows about well-known kinds.
+* Providers should supply their own resolver that includes their kinds.
+*/
+const defaultKindResolver = (name) => {
+	return require_well_known_kinds.WELL_KNOWN_KINDS_MAP.get(name);
+};
+const zodSchemaCache = /* @__PURE__ */ new WeakMap();
+/**
+* Convert JSON Schema to Zod schema with caching.
+*/
+function getZodSchema(jsonSchema) {
+	let zodSchema = zodSchemaCache.get(jsonSchema);
+	if (!zodSchema) {
+		zodSchema = (0, zod_from_json_schema.convertJsonSchemaToZod)(jsonSchema);
+		zodSchemaCache.set(jsonSchema, zodSchema);
+	}
+	return zodSchema;
+}
+/**
+* Define a new Kind with validation capabilities.
+*
+* @example
+* ```typescript
+* const projectKind = defineKind({
+*   name: "chamber:project",
+*   extends: "afs:node",
+*   description: "A project directory",
+*   meta: {
+*     type: "object",
+*     properties: {
+*       name: { type: "string" },
+*       status: { type: "string", enum: ["active", "archived"] },
+*     },
+*     required: ["name"],
+*   },
+*   nodes: {
+*     required: [{ path: "src" }],
+*     optional: [{ path: "*.md" }],
+*   },
+* });
+*
+* // Validate meta (includes parent validation)
+* const result = projectKind.validate({ name: "My Project", status: "active" });
+* ```
+*/
+function defineKind(definition) {
+	const schema = {
+		name: definition.name,
+		extends: definition.extends,
+		description: definition.description,
+		meta: definition.meta,
+		nodes: definition.nodes
+	};
+	return {
+		schema,
+		name: definition.name,
+		extends: definition.extends,
+		validate(meta, resolver = defaultKindResolver) {
+			const chain = this.getInheritanceChain(resolver);
+			const errors = [];
+			for (const kindSchema of chain) if (kindSchema.meta) try {
+				require_utils_zod.zodParse(getZodSchema(kindSchema.meta), meta, { prefix: kindSchema.name });
+			} catch (err) {
+				errors.push({
+					path: "",
+					message: err instanceof Error ? err.message : String(err),
+					code: "VALIDATION_ERROR"
+				});
+			}
+			return {
+				valid: errors.length === 0,
+				errors
+			};
+		},
+		validateNodes(basePath, nodeNames) {
+			return require_validation.validateNodes(basePath, nodeNames, schema.nodes);
+		},
+		getInheritanceChain(resolver = defaultKindResolver) {
+			return getInheritanceChain(schema, resolver);
+		}
+	};
+}
+/**
+* Get the inheritance chain from root ancestor to the given kind.
+*
+* @param kind - The kind to get inheritance chain for
+* @param resolver - Function to resolve kind by name
+* @returns Array of KindSchema from root to leaf (inclusive)
+* @throws Error if circular inheritance is detected or parent not found
+*/
+function getInheritanceChain(kind, resolver = defaultKindResolver) {
+	const chain = [];
+	const visited = /* @__PURE__ */ new Set();
+	let current = kind;
+	while (current) {
+		if (visited.has(current.name)) throw new Error(`Circular inheritance detected: ${current.name}`);
+		visited.add(current.name);
+		chain.unshift(current);
+		if (!current.extends) break;
+		current = resolver(current.extends);
+		if (!current) throw new Error(`Parent kind not found: "${kind.extends}" (extended by "${kind.name}")`);
+	}
+	return chain;
+}
+/**
+* Create a kind resolver that includes provider kinds and well-known kinds.
+*
+* @param providerKinds - Kinds defined by the provider
+* @returns A resolver function
+*/
+function createKindResolver(providerKinds) {
+	const providerMap = new Map(providerKinds.map((k) => [k.name, k]));
+	return (name) => {
+		const providerKind = providerMap.get(name);
+		if (providerKind) return providerKind;
+		return require_well_known_kinds.WELL_KNOWN_KINDS_MAP.get(name);
+	};
+}
+/**
+* Error thrown when kind resolution fails.
+*/
+var KindError = class extends Error {
+	constructor(message, kindName) {
+		super(message);
+		this.kindName = kindName;
+		this.name = "KindError";
+	}
+};
+/**
+* Resolve a kind name to its KindSchema.
+*
+* Looks up the kind in provider kinds first, then falls back to well-known kinds.
+*
+* @param kindName - The name of the kind to resolve (e.g., "afs:node", "chamber:project")
+* @param providerKinds - Optional array of kinds defined by the provider
+* @returns The resolved KindSchema, or undefined if not found
+*
+* @example
+* ```typescript
+* const nodeKind = resolveKindSchema("afs:node");
+* const projectKind = resolveKindSchema("chamber:project", providerKinds);
+* ```
+*/
+function resolveKindSchema(kindName, providerKinds) {
+	return (providerKinds ? createKindResolver(providerKinds) : defaultKindResolver)(kindName);
+}
+
+//#endregion
+exports.KindError = KindError;
+exports.createKindResolver = createKindResolver;
+exports.defaultKindResolver = defaultKindResolver;
+exports.defineKind = defineKind;
+exports.getInheritanceChain = getInheritanceChain;
+exports.resolveKindSchema = resolveKindSchema;

package/dist/meta/kind.d.cts

@@ -0,0 +1,134 @@
+import { JSONSchema7 } from "../node_modules/.pnpm/@types_json-schema@7.0.15/node_modules/@types/json-schema/index.cjs";
+import { KindSchema, NodesConstraints, ValidationResult } from "./type.cjs";
+
+//#region src/meta/kind.d.ts
+/**
+ * Input for defineKind function.
+ */
+interface KindDefinition {
+  /** Unique name in format "provider:kind" */
+  name: string;
+  /** Parent kind name for inheritance */
+  extends?: string;
+  /** Human-readable description */
+  description?: string;
+  /** Meta schema in JSON Schema format */
+  meta?: JSONSchema7;
+  /** Child node structure constraints */
+  nodes?: NodesConstraints;
+}
+/**
+ * A defined Kind with validation capabilities.
+ */
+interface Kind {
+  /** The underlying schema */
+  readonly schema: KindSchema;
+  /** Kind name */
+  readonly name: string;
+  /** Parent kind name */
+  readonly extends?: string;
+  /**
+   * Validate meta data against this kind and all ancestors.
+   * Performs layer-by-layer validation from root to leaf.
+   *
+   * @param meta - Meta data to validate
+   * @param resolver - Function to resolve kind by name (for inheritance)
+   * @returns Validation result with all errors from all layers
+   */
+  validate(meta: unknown, resolver?: KindResolver): ValidationResult;
+  /**
+   * Validate node structure against this kind's nodes constraints.
+   *
+   * @param basePath - Base path for error reporting (e.g., "/project")
+   * @param nodeNames - List of node names in the directory
+   * @returns Validation result
+   */
+  validateNodes(basePath: string, nodeNames: string[]): ValidationResult;
+  /**
+   * Get the inheritance chain from root to this kind.
+   *
+   * @param resolver - Function to resolve kind by name
+   * @returns Array of KindSchema from root ancestor to this kind
+   */
+  getInheritanceChain(resolver?: KindResolver): KindSchema[];
+}
+/**
+ * Function type for resolving a kind by name.
+ * Used for looking up parent kinds during inheritance resolution.
+ */
+type KindResolver = (name: string) => KindSchema | undefined;
+/**
+ * Default kind resolver that only knows about well-known kinds.
+ * Providers should supply their own resolver that includes their kinds.
+ */
+declare const defaultKindResolver: KindResolver;
+/**
+ * Define a new Kind with validation capabilities.
+ *
+ * @example
+ * ```typescript
+ * const projectKind = defineKind({
+ *   name: "chamber:project",
+ *   extends: "afs:node",
+ *   description: "A project directory",
+ *   meta: {
+ *     type: "object",
+ *     properties: {
+ *       name: { type: "string" },
+ *       status: { type: "string", enum: ["active", "archived"] },
+ *     },
+ *     required: ["name"],
+ *   },
+ *   nodes: {
+ *     required: [{ path: "src" }],
+ *     optional: [{ path: "*.md" }],
+ *   },
+ * });
+ *
+ * // Validate meta (includes parent validation)
+ * const result = projectKind.validate({ name: "My Project", status: "active" });
+ * ```
+ */
+declare function defineKind(definition: KindDefinition): Kind;
+/**
+ * Get the inheritance chain from root ancestor to the given kind.
+ *
+ * @param kind - The kind to get inheritance chain for
+ * @param resolver - Function to resolve kind by name
+ * @returns Array of KindSchema from root to leaf (inclusive)
+ * @throws Error if circular inheritance is detected or parent not found
+ */
+declare function getInheritanceChain(kind: KindSchema, resolver?: KindResolver): KindSchema[];
+/**
+ * Create a kind resolver that includes provider kinds and well-known kinds.
+ *
+ * @param providerKinds - Kinds defined by the provider
+ * @returns A resolver function
+ */
+declare function createKindResolver(providerKinds: KindSchema[]): KindResolver;
+/**
+ * Error thrown when kind resolution fails.
+ */
+declare class KindError extends Error {
+  readonly kindName: string;
+  constructor(message: string, kindName: string);
+}
+/**
+ * Resolve a kind name to its KindSchema.
+ *
+ * Looks up the kind in provider kinds first, then falls back to well-known kinds.
+ *
+ * @param kindName - The name of the kind to resolve (e.g., "afs:node", "chamber:project")
+ * @param providerKinds - Optional array of kinds defined by the provider
+ * @returns The resolved KindSchema, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const nodeKind = resolveKindSchema("afs:node");
+ * const projectKind = resolveKindSchema("chamber:project", providerKinds);
+ * ```
+ */
+declare function resolveKindSchema(kindName: string, providerKinds?: KindSchema[]): KindSchema | undefined;
+//#endregion
+export { Kind, KindDefinition, KindError, KindResolver, createKindResolver, defaultKindResolver, defineKind, getInheritanceChain, resolveKindSchema };
+//# sourceMappingURL=kind.d.cts.map

package/dist/meta/kind.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kind.d.cts","names":[],"sources":["../../src/meta/kind.ts"],"mappings":";;;;;;;UAyBiB,cAAA;EAUS;EARxB,IAAA;EAce;EAZf,OAAA;;EAEA,WAAA;EA4BmC;EA1BnC,IAAA,GAAO,WAAA;EAmC+C;EAjCtD,KAAA,GAAQ,gBAAA;AAAA;;;;UAMO,IAAA;EAKN;EAAA,SAHA,MAAA,EAAQ,UAAA;EAgBjB;EAAA,SAbS,IAAA;EAa0B;EAAA,SAV1B,OAAA;EAUyC;;;;;;;;EAAlD,QAAA,CAAS,IAAA,WAAe,QAAA,GAAW,YAAA,GAAe,gBAAA;EAiBM;;AAO1D;;;;;EAfE,aAAA,CAAc,QAAA,UAAkB,SAAA,aAAsB,gBAAA;EA2BvD;;;;AAmDD;;EAtEE,mBAAA,CAAoB,QAAA,GAAW,YAAA,GAAe,UAAA;AAAA;;;;;KAOpC,YAAA,IAAgB,IAAA,aAAiB,UAAA;AAyH7C;;;;AAAA,cA/Ga,mBAAA,EAAqB,YAAA;;;;;;;;;;;AAkJlC;;;;;;;;;AAqBA;;;;;;;;iBAlHgB,UAAA,CAAW,UAAA,EAAY,cAAA,GAAiB,IAAA;;;AA2IxD;;;;;;iBAjFgB,mBAAA,CACd,IAAA,EAAM,UAAA,EACN,QAAA,GAAU,YAAA,GACT,UAAA;;;;;;;iBAgCa,kBAAA,CAAmB,aAAA,EAAe,UAAA,KAAe,YAAA;;;;cAqBpD,SAAA,SAAkB,KAAA;EAAA,SAGX,QAAA;cADhB,OAAA,UACgB,QAAA;AAAA;;;;;;;;;;;;;;;;iBAsBJ,iBAAA,CACd,QAAA,UACA,aAAA,GAAgB,UAAA,KACf,UAAA"}

package/dist/meta/kind.d.mts

@@ -0,0 +1,134 @@
+import { JSONSchema7 } from "../node_modules/.pnpm/@types_json-schema@7.0.15/node_modules/@types/json-schema/index.mjs";
+import { KindSchema, NodesConstraints, ValidationResult } from "./type.mjs";
+
+//#region src/meta/kind.d.ts
+/**
+ * Input for defineKind function.
+ */
+interface KindDefinition {
+  /** Unique name in format "provider:kind" */
+  name: string;
+  /** Parent kind name for inheritance */
+  extends?: string;
+  /** Human-readable description */
+  description?: string;
+  /** Meta schema in JSON Schema format */
+  meta?: JSONSchema7;
+  /** Child node structure constraints */
+  nodes?: NodesConstraints;
+}
+/**
+ * A defined Kind with validation capabilities.
+ */
+interface Kind {
+  /** The underlying schema */
+  readonly schema: KindSchema;
+  /** Kind name */
+  readonly name: string;
+  /** Parent kind name */
+  readonly extends?: string;
+  /**
+   * Validate meta data against this kind and all ancestors.
+   * Performs layer-by-layer validation from root to leaf.
+   *
+   * @param meta - Meta data to validate
+   * @param resolver - Function to resolve kind by name (for inheritance)
+   * @returns Validation result with all errors from all layers
+   */
+  validate(meta: unknown, resolver?: KindResolver): ValidationResult;
+  /**
+   * Validate node structure against this kind's nodes constraints.
+   *
+   * @param basePath - Base path for error reporting (e.g., "/project")
+   * @param nodeNames - List of node names in the directory
+   * @returns Validation result
+   */
+  validateNodes(basePath: string, nodeNames: string[]): ValidationResult;
+  /**
+   * Get the inheritance chain from root to this kind.
+   *
+   * @param resolver - Function to resolve kind by name
+   * @returns Array of KindSchema from root ancestor to this kind
+   */
+  getInheritanceChain(resolver?: KindResolver): KindSchema[];
+}
+/**
+ * Function type for resolving a kind by name.
+ * Used for looking up parent kinds during inheritance resolution.
+ */
+type KindResolver = (name: string) => KindSchema | undefined;
+/**
+ * Default kind resolver that only knows about well-known kinds.
+ * Providers should supply their own resolver that includes their kinds.
+ */
+declare const defaultKindResolver: KindResolver;
+/**
+ * Define a new Kind with validation capabilities.
+ *
+ * @example
+ * ```typescript
+ * const projectKind = defineKind({
+ *   name: "chamber:project",
+ *   extends: "afs:node",
+ *   description: "A project directory",
+ *   meta: {
+ *     type: "object",
+ *     properties: {
+ *       name: { type: "string" },
+ *       status: { type: "string", enum: ["active", "archived"] },
+ *     },
+ *     required: ["name"],
+ *   },
+ *   nodes: {
+ *     required: [{ path: "src" }],
+ *     optional: [{ path: "*.md" }],
+ *   },
+ * });
+ *
+ * // Validate meta (includes parent validation)
+ * const result = projectKind.validate({ name: "My Project", status: "active" });
+ * ```
+ */
+declare function defineKind(definition: KindDefinition): Kind;
+/**
+ * Get the inheritance chain from root ancestor to the given kind.
+ *
+ * @param kind - The kind to get inheritance chain for
+ * @param resolver - Function to resolve kind by name
+ * @returns Array of KindSchema from root to leaf (inclusive)
+ * @throws Error if circular inheritance is detected or parent not found
+ */
+declare function getInheritanceChain(kind: KindSchema, resolver?: KindResolver): KindSchema[];
+/**
+ * Create a kind resolver that includes provider kinds and well-known kinds.
+ *
+ * @param providerKinds - Kinds defined by the provider
+ * @returns A resolver function
+ */
+declare function createKindResolver(providerKinds: KindSchema[]): KindResolver;
+/**
+ * Error thrown when kind resolution fails.
+ */
+declare class KindError extends Error {
+  readonly kindName: string;
+  constructor(message: string, kindName: string);
+}
+/**
+ * Resolve a kind name to its KindSchema.
+ *
+ * Looks up the kind in provider kinds first, then falls back to well-known kinds.
+ *
+ * @param kindName - The name of the kind to resolve (e.g., "afs:node", "chamber:project")
+ * @param providerKinds - Optional array of kinds defined by the provider
+ * @returns The resolved KindSchema, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const nodeKind = resolveKindSchema("afs:node");
+ * const projectKind = resolveKindSchema("chamber:project", providerKinds);
+ * ```
+ */
+declare function resolveKindSchema(kindName: string, providerKinds?: KindSchema[]): KindSchema | undefined;
+//#endregion
+export { Kind, KindDefinition, KindError, KindResolver, createKindResolver, defaultKindResolver, defineKind, getInheritanceChain, resolveKindSchema };
+//# sourceMappingURL=kind.d.mts.map

package/dist/meta/kind.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kind.d.mts","names":[],"sources":["../../src/meta/kind.ts"],"mappings":";;;;;;;UAyBiB,cAAA;EAUS;EARxB,IAAA;EAce;EAZf,OAAA;;EAEA,WAAA;EA4BmC;EA1BnC,IAAA,GAAO,WAAA;EAmC+C;EAjCtD,KAAA,GAAQ,gBAAA;AAAA;;;;UAMO,IAAA;EAKN;EAAA,SAHA,MAAA,EAAQ,UAAA;EAgBjB;EAAA,SAbS,IAAA;EAa0B;EAAA,SAV1B,OAAA;EAUyC;;;;;;;;EAAlD,QAAA,CAAS,IAAA,WAAe,QAAA,GAAW,YAAA,GAAe,gBAAA;EAiBM;;AAO1D;;;;;EAfE,aAAA,CAAc,QAAA,UAAkB,SAAA,aAAsB,gBAAA;EA2BvD;;;;AAmDD;;EAtEE,mBAAA,CAAoB,QAAA,GAAW,YAAA,GAAe,UAAA;AAAA;;;;;KAOpC,YAAA,IAAgB,IAAA,aAAiB,UAAA;AAyH7C;;;;AAAA,cA/Ga,mBAAA,EAAqB,YAAA;;;;;;;;;;;AAkJlC;;;;;;;;;AAqBA;;;;;;;;iBAlHgB,UAAA,CAAW,UAAA,EAAY,cAAA,GAAiB,IAAA;;;AA2IxD;;;;;;iBAjFgB,mBAAA,CACd,IAAA,EAAM,UAAA,EACN,QAAA,GAAU,YAAA,GACT,UAAA;;;;;;;iBAgCa,kBAAA,CAAmB,aAAA,EAAe,UAAA,KAAe,YAAA;;;;cAqBpD,SAAA,SAAkB,KAAA;EAAA,SAGX,QAAA;cADhB,OAAA,UACgB,QAAA;AAAA;;;;;;;;;;;;;;;;iBAsBJ,iBAAA,CACd,QAAA,UACA,aAAA,GAAgB,UAAA,KACf,UAAA"}

package/dist/meta/kind.mjs

@@ -0,0 +1,157 @@
+import { zodParse } from "../utils/zod.mjs";
+import { validateNodes } from "./validation.mjs";
+import { WELL_KNOWN_KINDS_MAP } from "./well-known-kinds.mjs";
+import { convertJsonSchemaToZod } from "zod-from-json-schema";
+
+//#region src/meta/kind.ts
+/**
+* Default kind resolver that only knows about well-known kinds.
+* Providers should supply their own resolver that includes their kinds.
+*/
+const defaultKindResolver = (name) => {
+	return WELL_KNOWN_KINDS_MAP.get(name);
+};
+const zodSchemaCache = /* @__PURE__ */ new WeakMap();
+/**
+* Convert JSON Schema to Zod schema with caching.
+*/
+function getZodSchema(jsonSchema) {
+	let zodSchema = zodSchemaCache.get(jsonSchema);
+	if (!zodSchema) {
+		zodSchema = convertJsonSchemaToZod(jsonSchema);
+		zodSchemaCache.set(jsonSchema, zodSchema);
+	}
+	return zodSchema;
+}
+/**
+* Define a new Kind with validation capabilities.
+*
+* @example
+* ```typescript
+* const projectKind = defineKind({
+*   name: "chamber:project",
+*   extends: "afs:node",
+*   description: "A project directory",
+*   meta: {
+*     type: "object",
+*     properties: {
+*       name: { type: "string" },
+*       status: { type: "string", enum: ["active", "archived"] },
+*     },
+*     required: ["name"],
+*   },
+*   nodes: {
+*     required: [{ path: "src" }],
+*     optional: [{ path: "*.md" }],
+*   },
+* });
+*
+* // Validate meta (includes parent validation)
+* const result = projectKind.validate({ name: "My Project", status: "active" });
+* ```
+*/
+function defineKind(definition) {
+	const schema = {
+		name: definition.name,
+		extends: definition.extends,
+		description: definition.description,
+		meta: definition.meta,
+		nodes: definition.nodes
+	};
+	return {
+		schema,
+		name: definition.name,
+		extends: definition.extends,
+		validate(meta, resolver = defaultKindResolver) {
+			const chain = this.getInheritanceChain(resolver);
+			const errors = [];
+			for (const kindSchema of chain) if (kindSchema.meta) try {
+				zodParse(getZodSchema(kindSchema.meta), meta, { prefix: kindSchema.name });
+			} catch (err) {
+				errors.push({
+					path: "",
+					message: err instanceof Error ? err.message : String(err),
+					code: "VALIDATION_ERROR"
+				});
+			}
+			return {
+				valid: errors.length === 0,
+				errors
+			};
+		},
+		validateNodes(basePath, nodeNames) {
+			return validateNodes(basePath, nodeNames, schema.nodes);
+		},
+		getInheritanceChain(resolver = defaultKindResolver) {
+			return getInheritanceChain(schema, resolver);
+		}
+	};
+}
+/**
+* Get the inheritance chain from root ancestor to the given kind.
+*
+* @param kind - The kind to get inheritance chain for
+* @param resolver - Function to resolve kind by name
+* @returns Array of KindSchema from root to leaf (inclusive)
+* @throws Error if circular inheritance is detected or parent not found
+*/
+function getInheritanceChain(kind, resolver = defaultKindResolver) {
+	const chain = [];
+	const visited = /* @__PURE__ */ new Set();
+	let current = kind;
+	while (current) {
+		if (visited.has(current.name)) throw new Error(`Circular inheritance detected: ${current.name}`);
+		visited.add(current.name);
+		chain.unshift(current);
+		if (!current.extends) break;
+		current = resolver(current.extends);
+		if (!current) throw new Error(`Parent kind not found: "${kind.extends}" (extended by "${kind.name}")`);
+	}
+	return chain;
+}
+/**
+* Create a kind resolver that includes provider kinds and well-known kinds.
+*
+* @param providerKinds - Kinds defined by the provider
+* @returns A resolver function
+*/
+function createKindResolver(providerKinds) {
+	const providerMap = new Map(providerKinds.map((k) => [k.name, k]));
+	return (name) => {
+		const providerKind = providerMap.get(name);
+		if (providerKind) return providerKind;
+		return WELL_KNOWN_KINDS_MAP.get(name);
+	};
+}
+/**
+* Error thrown when kind resolution fails.
+*/
+var KindError = class extends Error {
+	constructor(message, kindName) {
+		super(message);
+		this.kindName = kindName;
+		this.name = "KindError";
+	}
+};
+/**
+* Resolve a kind name to its KindSchema.
+*
+* Looks up the kind in provider kinds first, then falls back to well-known kinds.
+*
+* @param kindName - The name of the kind to resolve (e.g., "afs:node", "chamber:project")
+* @param providerKinds - Optional array of kinds defined by the provider
+* @returns The resolved KindSchema, or undefined if not found
+*
+* @example
+* ```typescript
+* const nodeKind = resolveKindSchema("afs:node");
+* const projectKind = resolveKindSchema("chamber:project", providerKinds);
+* ```
+*/
+function resolveKindSchema(kindName, providerKinds) {
+	return (providerKinds ? createKindResolver(providerKinds) : defaultKindResolver)(kindName);
+}
+
+//#endregion
+export { KindError, createKindResolver, defaultKindResolver, defineKind, getInheritanceChain, resolveKindSchema };
+//# sourceMappingURL=kind.mjs.map

package/dist/meta/kind.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"kind.mjs","names":[],"sources":["../../src/meta/kind.ts"],"sourcesContent":["/**\n * Kind System - defineKind API with layer-by-layer validation\n *\n * Provides:\n * - defineKind() function for creating Kind definitions\n * - Layer-by-layer validation (validates each ancestor separately)\n * - Inheritance chain resolution\n *\n * Uses zod-from-json-schema for runtime JSON Schema to Zod conversion.\n */\n\nimport type { ZodType } from \"zod\";\nimport { convertJsonSchemaToZod } from \"zod-from-json-schema\";\nimport { zodParse } from \"../utils/zod.js\";\nimport type { JSONSchema7, KindSchema, NodesConstraints, ValidationResult } from \"./type.js\";\nimport { validateNodes } from \"./validation.js\";\nimport { WELL_KNOWN_KINDS_MAP } from \"./well-known-kinds.js\";\n\n// =============================================================================\n// Kind definition and instance types\n// =============================================================================\n\n/**\n * Input for defineKind function.\n */\nexport interface KindDefinition {\n  /** Unique name in format \"provider:kind\" */\n  name: string;\n  /** Parent kind name for inheritance */\n  extends?: string;\n  /** Human-readable description */\n  description?: string;\n  /** Meta schema in JSON Schema format */\n  meta?: JSONSchema7;\n  /** Child node structure constraints */\n  nodes?: NodesConstraints;\n}\n\n/**\n * A defined Kind with validation capabilities.\n */\nexport interface Kind {\n  /** The underlying schema */\n  readonly schema: KindSchema;\n\n  /** Kind name */\n  readonly name: string;\n\n  /** Parent kind name */\n  readonly extends?: string;\n\n  /**\n   * Validate meta data against this kind and all ancestors.\n   * Performs layer-by-layer validation from root to leaf.\n   *\n   * @param meta - Meta data to validate\n   * @param resolver - Function to resolve kind by name (for inheritance)\n   * @returns Validation result with all errors from all layers\n   */\n  validate(meta: unknown, resolver?: KindResolver): ValidationResult;\n\n  /**\n   * Validate node structure against this kind's nodes constraints.\n   *\n   * @param basePath - Base path for error reporting (e.g., \"/project\")\n   * @param nodeNames - List of node names in the directory\n   * @returns Validation result\n   */\n  validateNodes(basePath: string, nodeNames: string[]): ValidationResult;\n\n  /**\n   * Get the inheritance chain from root to this kind.\n   *\n   * @param resolver - Function to resolve kind by name\n   * @returns Array of KindSchema from root ancestor to this kind\n   */\n  getInheritanceChain(resolver?: KindResolver): KindSchema[];\n}\n\n/**\n * Function type for resolving a kind by name.\n * Used for looking up parent kinds during inheritance resolution.\n */\nexport type KindResolver = (name: string) => KindSchema | undefined;\n\n// =============================================================================\n// Default resolver (uses well-known kinds)\n// =============================================================================\n\n/**\n * Default kind resolver that only knows about well-known kinds.\n * Providers should supply their own resolver that includes their kinds.\n */\nexport const defaultKindResolver: KindResolver = (name: string) => {\n  return WELL_KNOWN_KINDS_MAP.get(name);\n};\n\n// =============================================================================\n// Schema cache for performance\n// =============================================================================\n\nconst zodSchemaCache = new WeakMap<JSONSchema7, ZodType>();\n\n/**\n * Convert JSON Schema to Zod schema with caching.\n */\nfunction getZodSchema(jsonSchema: JSONSchema7): ZodType {\n  let zodSchema = zodSchemaCache.get(jsonSchema);\n  if (!zodSchema) {\n    zodSchema = convertJsonSchemaToZod(jsonSchema as any);\n    zodSchemaCache.set(jsonSchema, zodSchema);\n  }\n  return zodSchema;\n}\n\n// =============================================================================\n// defineKind implementation\n// =============================================================================\n\n/**\n * Define a new Kind with validation capabilities.\n *\n * @example\n * ```typescript\n * const projectKind = defineKind({\n *   name: \"chamber:project\",\n *   extends: \"afs:node\",\n *   description: \"A project directory\",\n *   meta: {\n *     type: \"object\",\n *     properties: {\n *       name: { type: \"string\" },\n *       status: { type: \"string\", enum: [\"active\", \"archived\"] },\n *     },\n *     required: [\"name\"],\n *   },\n *   nodes: {\n *     required: [{ path: \"src\" }],\n *     optional: [{ path: \"*.md\" }],\n *   },\n * });\n *\n * // Validate meta (includes parent validation)\n * const result = projectKind.validate({ name: \"My Project\", status: \"active\" });\n * ```\n */\nexport function defineKind(definition: KindDefinition): Kind {\n  const schema: KindSchema = {\n    name: definition.name,\n    extends: definition.extends,\n    description: definition.description,\n    meta: definition.meta,\n    nodes: definition.nodes,\n  };\n\n  return {\n    schema,\n    name: definition.name,\n    extends: definition.extends,\n\n    validate(meta: unknown, resolver: KindResolver = defaultKindResolver): ValidationResult {\n      const chain = this.getInheritanceChain(resolver);\n      const errors: ValidationResult[\"errors\"] = [];\n\n      // Validate each layer from root to leaf\n      for (const kindSchema of chain) {\n        if (kindSchema.meta) {\n          try {\n            zodParse(getZodSchema(kindSchema.meta), meta, { prefix: kindSchema.name });\n          } catch (err) {\n            errors.push({\n              path: \"\",\n              message: err instanceof Error ? err.message : String(err),\n              code: \"VALIDATION_ERROR\",\n            });\n          }\n        }\n      }\n\n      return { valid: errors.length === 0, errors };\n    },\n\n    validateNodes(basePath: string, nodeNames: string[]): ValidationResult {\n      return validateNodes(basePath, nodeNames, schema.nodes);\n    },\n\n    getInheritanceChain(resolver: KindResolver = defaultKindResolver): KindSchema[] {\n      return getInheritanceChain(schema, resolver);\n    },\n  };\n}\n\n// =============================================================================\n// Inheritance helpers\n// =============================================================================\n\n/**\n * Get the inheritance chain from root ancestor to the given kind.\n *\n * @param kind - The kind to get inheritance chain for\n * @param resolver - Function to resolve kind by name\n * @returns Array of KindSchema from root to leaf (inclusive)\n * @throws Error if circular inheritance is detected or parent not found\n */\nexport function getInheritanceChain(\n  kind: KindSchema,\n  resolver: KindResolver = defaultKindResolver,\n): KindSchema[] {\n  const chain: KindSchema[] = [];\n  const visited = new Set<string>();\n  let current: KindSchema | undefined = kind;\n\n  // Walk up the inheritance tree\n  while (current) {\n    if (visited.has(current.name)) {\n      throw new Error(`Circular inheritance detected: ${current.name}`);\n    }\n    visited.add(current.name);\n    chain.unshift(current); // Add to front (we're walking up)\n\n    if (!current.extends) {\n      break;\n    }\n\n    current = resolver(current.extends);\n    if (!current) {\n      throw new Error(`Parent kind not found: \"${kind.extends}\" (extended by \"${kind.name}\")`);\n    }\n  }\n\n  return chain;\n}\n\n/**\n * Create a kind resolver that includes provider kinds and well-known kinds.\n *\n * @param providerKinds - Kinds defined by the provider\n * @returns A resolver function\n */\nexport function createKindResolver(providerKinds: KindSchema[]): KindResolver {\n  const providerMap = new Map(providerKinds.map((k) => [k.name, k]));\n\n  return (name: string) => {\n    // Provider kinds take precedence\n    const providerKind = providerMap.get(name);\n    if (providerKind) {\n      return providerKind;\n    }\n    // Fall back to well-known kinds\n    return WELL_KNOWN_KINDS_MAP.get(name);\n  };\n}\n\n// =============================================================================\n// Utility exports\n// =============================================================================\n\n/**\n * Error thrown when kind resolution fails.\n */\nexport class KindError extends Error {\n  constructor(\n    message: string,\n    public readonly kindName: string,\n  ) {\n    super(message);\n    this.name = \"KindError\";\n  }\n}\n\n/**\n * Resolve a kind name to its KindSchema.\n *\n * Looks up the kind in provider kinds first, then falls back to well-known kinds.\n *\n * @param kindName - The name of the kind to resolve (e.g., \"afs:node\", \"chamber:project\")\n * @param providerKinds - Optional array of kinds defined by the provider\n * @returns The resolved KindSchema, or undefined if not found\n *\n * @example\n * ```typescript\n * const nodeKind = resolveKindSchema(\"afs:node\");\n * const projectKind = resolveKindSchema(\"chamber:project\", providerKinds);\n * ```\n */\nexport function resolveKindSchema(\n  kindName: string,\n  providerKinds?: KindSchema[],\n): KindSchema | undefined {\n  const resolver = providerKinds ? createKindResolver(providerKinds) : defaultKindResolver;\n  return resolver(kindName);\n}\n"],"mappings":";;;;;;;;;;AA6FA,MAAa,uBAAqC,SAAiB;AACjE,QAAO,qBAAqB,IAAI,KAAK;;AAOvC,MAAM,iCAAiB,IAAI,SAA+B;;;;AAK1D,SAAS,aAAa,YAAkC;CACtD,IAAI,YAAY,eAAe,IAAI,WAAW;AAC9C,KAAI,CAAC,WAAW;AACd,cAAY,uBAAuB,WAAkB;AACrD,iBAAe,IAAI,YAAY,UAAU;;AAE3C,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCT,SAAgB,WAAW,YAAkC;CAC3D,MAAM,SAAqB;EACzB,MAAM,WAAW;EACjB,SAAS,WAAW;EACpB,aAAa,WAAW;EACxB,MAAM,WAAW;EACjB,OAAO,WAAW;EACnB;AAED,QAAO;EACL;EACA,MAAM,WAAW;EACjB,SAAS,WAAW;EAEpB,SAAS,MAAe,WAAyB,qBAAuC;GACtF,MAAM,QAAQ,KAAK,oBAAoB,SAAS;GAChD,MAAM,SAAqC,EAAE;AAG7C,QAAK,MAAM,cAAc,MACvB,KAAI,WAAW,KACb,KAAI;AACF,aAAS,aAAa,WAAW,KAAK,EAAE,MAAM,EAAE,QAAQ,WAAW,MAAM,CAAC;YACnE,KAAK;AACZ,WAAO,KAAK;KACV,MAAM;KACN,SAAS,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI;KACzD,MAAM;KACP,CAAC;;AAKR,UAAO;IAAE,OAAO,OAAO,WAAW;IAAG;IAAQ;;EAG/C,cAAc,UAAkB,WAAuC;AACrE,UAAO,cAAc,UAAU,WAAW,OAAO,MAAM;;EAGzD,oBAAoB,WAAyB,qBAAmC;AAC9E,UAAO,oBAAoB,QAAQ,SAAS;;EAE/C;;;;;;;;;;AAeH,SAAgB,oBACd,MACA,WAAyB,qBACX;CACd,MAAM,QAAsB,EAAE;CAC9B,MAAM,0BAAU,IAAI,KAAa;CACjC,IAAI,UAAkC;AAGtC,QAAO,SAAS;AACd,MAAI,QAAQ,IAAI,QAAQ,KAAK,CAC3B,OAAM,IAAI,MAAM,kCAAkC,QAAQ,OAAO;AAEnE,UAAQ,IAAI,QAAQ,KAAK;AACzB,QAAM,QAAQ,QAAQ;AAEtB,MAAI,CAAC,QAAQ,QACX;AAGF,YAAU,SAAS,QAAQ,QAAQ;AACnC,MAAI,CAAC,QACH,OAAM,IAAI,MAAM,2BAA2B,KAAK,QAAQ,kBAAkB,KAAK,KAAK,IAAI;;AAI5F,QAAO;;;;;;;;AAST,SAAgB,mBAAmB,eAA2C;CAC5E,MAAM,cAAc,IAAI,IAAI,cAAc,KAAK,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;AAElE,SAAQ,SAAiB;EAEvB,MAAM,eAAe,YAAY,IAAI,KAAK;AAC1C,MAAI,aACF,QAAO;AAGT,SAAO,qBAAqB,IAAI,KAAK;;;;;;AAWzC,IAAa,YAAb,cAA+B,MAAM;CACnC,YACE,SACA,AAAgB,UAChB;AACA,QAAM,QAAQ;EAFE;AAGhB,OAAK,OAAO;;;;;;;;;;;;;;;;;;AAmBhB,SAAgB,kBACd,UACA,eACwB;AAExB,SADiB,gBAAgB,mBAAmB,cAAc,GAAG,qBACrD,SAAS"}