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

package/dist/meta/path.cjs

@@ -0,0 +1,116 @@
+const require_path = require('../path.cjs');
+
+//#region src/meta/path.ts
+/**
+* Meta Path Utilities for AFS
+*
+* Provides functions to work with .meta virtual paths:
+* - /dir/.meta - directory metadata
+* - /dir/.meta/icon.png - directory meta resource
+* - /dir/file.txt/.meta - file metadata
+* - /.meta/.kinds - provider kinds list
+* - /.meta/.kinds/chamber:project - specific kind
+*/
+/** The .meta virtual path segment */
+const META_SEGMENT = ".meta";
+/** The .kinds virtual path segment (under .meta) */
+const KINDS_SEGMENT = ".kinds";
+/**
+* Check if a path is a .meta virtual path.
+*
+* A path is considered a meta path if it contains "/.meta" as a path segment
+* (not just a substring of a filename).
+*
+* @param path - Path to check
+* @returns true if the path is a .meta path
+*/
+function isMetaPath(path) {
+	if (!path) return false;
+	let normalizedPath;
+	try {
+		const trimmedPath = path.endsWith("/") ? path.slice(0, -1) : path;
+		if (!trimmedPath.startsWith("/")) return false;
+		normalizedPath = require_path.normalizePath(trimmedPath);
+	} catch {
+		return false;
+	}
+	const segments = normalizedPath.split("/");
+	for (let i = 0; i < segments.length; i++) if (segments[i] === META_SEGMENT) return true;
+	return false;
+}
+/**
+* Parse a .meta virtual path into its components.
+*
+* @param path - Meta path to parse (must be absolute and contain .meta)
+* @returns Parsed MetaPathInfo
+* @throws AFSPathError if path is invalid or not a meta path
+*/
+function parseMetaPath(path) {
+	if (!path || path.trim() === "") throw new require_path.AFSPathError("Meta path cannot be empty", path);
+	if (!path.startsWith("/")) throw new require_path.AFSPathError("Meta path must be absolute (start with /)", path);
+	let normalizedPath;
+	try {
+		normalizedPath = require_path.validatePath(path.endsWith("/") ? path.slice(0, -1) : path);
+	} catch (e) {
+		if (e instanceof require_path.AFSPathError) throw e;
+		throw new require_path.AFSPathError(`Invalid meta path: ${path}`, path);
+	}
+	const segments = normalizedPath.split("/");
+	let metaIndex = -1;
+	for (let i = 0; i < segments.length; i++) if (segments[i] === META_SEGMENT) {
+		metaIndex = i;
+		break;
+	}
+	if (metaIndex === -1) throw new require_path.AFSPathError(`Path does not contain .meta: ${path}`, path);
+	const nodeSegments = segments.slice(0, metaIndex);
+	const nodePath = nodeSegments.length === 0 ? "/" : `/${nodeSegments.filter(Boolean).join("/")}`;
+	const afterMetaSegments = segments.slice(metaIndex + 1);
+	if (afterMetaSegments.length > 0 && afterMetaSegments[0] === KINDS_SEGMENT) {
+		const kindName = afterMetaSegments.length > 1 ? afterMetaSegments.slice(1).join("/") : null;
+		return {
+			nodePath: nodePath === "" ? "/" : nodePath,
+			resourcePath: null,
+			isKindsPath: true,
+			kindName: kindName || null
+		};
+	}
+	const resourcePath = afterMetaSegments.length > 0 ? afterMetaSegments.join("/") : null;
+	return {
+		nodePath: nodePath === "" ? "/" : nodePath,
+		resourcePath,
+		isKindsPath: false,
+		kindName: null
+	};
+}
+/**
+* Check if a path is a .meta/.kinds path.
+*
+* @param path - Path to check
+* @returns true if the path is a kinds path
+*/
+function isKindsPath(path) {
+	if (!path || !isMetaPath(path)) return false;
+	try {
+		return parseMetaPath(path).isKindsPath;
+	} catch {
+		return false;
+	}
+}
+/**
+* Extract the node path from a meta path.
+*
+* @param metaPath - Meta path
+* @returns Node path (without .meta and after)
+* @throws AFSPathError if path is invalid or not a meta path
+*/
+function getNodePathFromMetaPath(metaPath) {
+	return parseMetaPath(metaPath).nodePath;
+}
+
+//#endregion
+exports.KINDS_SEGMENT = KINDS_SEGMENT;
+exports.META_SEGMENT = META_SEGMENT;
+exports.getNodePathFromMetaPath = getNodePathFromMetaPath;
+exports.isKindsPath = isKindsPath;
+exports.isMetaPath = isMetaPath;
+exports.parseMetaPath = parseMetaPath;

package/dist/meta/path.d.cts

@@ -0,0 +1,43 @@
+import { MetaPathInfo } from "./type.cjs";
+
+//#region src/meta/path.d.ts
+/** The .meta virtual path segment */
+declare const META_SEGMENT = ".meta";
+/** The .kinds virtual path segment (under .meta) */
+declare const KINDS_SEGMENT = ".kinds";
+/**
+ * Check if a path is a .meta virtual path.
+ *
+ * A path is considered a meta path if it contains "/.meta" as a path segment
+ * (not just a substring of a filename).
+ *
+ * @param path - Path to check
+ * @returns true if the path is a .meta path
+ */
+declare function isMetaPath(path: string): boolean;
+/**
+ * Parse a .meta virtual path into its components.
+ *
+ * @param path - Meta path to parse (must be absolute and contain .meta)
+ * @returns Parsed MetaPathInfo
+ * @throws AFSPathError if path is invalid or not a meta path
+ */
+declare function parseMetaPath(path: string): MetaPathInfo;
+/**
+ * Check if a path is a .meta/.kinds path.
+ *
+ * @param path - Path to check
+ * @returns true if the path is a kinds path
+ */
+declare function isKindsPath(path: string): boolean;
+/**
+ * Extract the node path from a meta path.
+ *
+ * @param metaPath - Meta path
+ * @returns Node path (without .meta and after)
+ * @throws AFSPathError if path is invalid or not a meta path
+ */
+declare function getNodePathFromMetaPath(metaPath: string): string;
+//#endregion
+export { KINDS_SEGMENT, META_SEGMENT, getNodePathFromMetaPath, isKindsPath, isMetaPath, parseMetaPath };
+//# sourceMappingURL=path.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.cts","names":[],"sources":["../../src/meta/path.ts"],"mappings":";;;;cAea,YAAA;AAcb;AAAA,cAXa,aAAA;;;;AAiDb;;;;;AAyEA;iBA/GgB,UAAA,CAAW,IAAA;;;;AAmI3B;;;;iBA7FgB,aAAA,CAAc,IAAA,WAAe,YAAA;;;;;;;iBAyE7B,WAAA,CAAY,IAAA;;;;;;;;iBAoBZ,uBAAA,CAAwB,QAAA"}

package/dist/meta/path.d.mts

@@ -0,0 +1,43 @@
+import { MetaPathInfo } from "./type.mjs";
+
+//#region src/meta/path.d.ts
+/** The .meta virtual path segment */
+declare const META_SEGMENT = ".meta";
+/** The .kinds virtual path segment (under .meta) */
+declare const KINDS_SEGMENT = ".kinds";
+/**
+ * Check if a path is a .meta virtual path.
+ *
+ * A path is considered a meta path if it contains "/.meta" as a path segment
+ * (not just a substring of a filename).
+ *
+ * @param path - Path to check
+ * @returns true if the path is a .meta path
+ */
+declare function isMetaPath(path: string): boolean;
+/**
+ * Parse a .meta virtual path into its components.
+ *
+ * @param path - Meta path to parse (must be absolute and contain .meta)
+ * @returns Parsed MetaPathInfo
+ * @throws AFSPathError if path is invalid or not a meta path
+ */
+declare function parseMetaPath(path: string): MetaPathInfo;
+/**
+ * Check if a path is a .meta/.kinds path.
+ *
+ * @param path - Path to check
+ * @returns true if the path is a kinds path
+ */
+declare function isKindsPath(path: string): boolean;
+/**
+ * Extract the node path from a meta path.
+ *
+ * @param metaPath - Meta path
+ * @returns Node path (without .meta and after)
+ * @throws AFSPathError if path is invalid or not a meta path
+ */
+declare function getNodePathFromMetaPath(metaPath: string): string;
+//#endregion
+export { KINDS_SEGMENT, META_SEGMENT, getNodePathFromMetaPath, isKindsPath, isMetaPath, parseMetaPath };
+//# sourceMappingURL=path.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.mts","names":[],"sources":["../../src/meta/path.ts"],"mappings":";;;;cAea,YAAA;AAcb;AAAA,cAXa,aAAA;;;;AAiDb;;;;;AAyEA;iBA/GgB,UAAA,CAAW,IAAA;;;;AAmI3B;;;;iBA7FgB,aAAA,CAAc,IAAA,WAAe,YAAA;;;;;;;iBAyE7B,WAAA,CAAY,IAAA;;;;;;;;iBAoBZ,uBAAA,CAAwB,QAAA"}

package/dist/meta/path.mjs

@@ -0,0 +1,112 @@
+import { AFSPathError, normalizePath, validatePath } from "../path.mjs";
+
+//#region src/meta/path.ts
+/**
+* Meta Path Utilities for AFS
+*
+* Provides functions to work with .meta virtual paths:
+* - /dir/.meta - directory metadata
+* - /dir/.meta/icon.png - directory meta resource
+* - /dir/file.txt/.meta - file metadata
+* - /.meta/.kinds - provider kinds list
+* - /.meta/.kinds/chamber:project - specific kind
+*/
+/** The .meta virtual path segment */
+const META_SEGMENT = ".meta";
+/** The .kinds virtual path segment (under .meta) */
+const KINDS_SEGMENT = ".kinds";
+/**
+* Check if a path is a .meta virtual path.
+*
+* A path is considered a meta path if it contains "/.meta" as a path segment
+* (not just a substring of a filename).
+*
+* @param path - Path to check
+* @returns true if the path is a .meta path
+*/
+function isMetaPath(path) {
+	if (!path) return false;
+	let normalizedPath;
+	try {
+		const trimmedPath = path.endsWith("/") ? path.slice(0, -1) : path;
+		if (!trimmedPath.startsWith("/")) return false;
+		normalizedPath = normalizePath(trimmedPath);
+	} catch {
+		return false;
+	}
+	const segments = normalizedPath.split("/");
+	for (let i = 0; i < segments.length; i++) if (segments[i] === META_SEGMENT) return true;
+	return false;
+}
+/**
+* Parse a .meta virtual path into its components.
+*
+* @param path - Meta path to parse (must be absolute and contain .meta)
+* @returns Parsed MetaPathInfo
+* @throws AFSPathError if path is invalid or not a meta path
+*/
+function parseMetaPath(path) {
+	if (!path || path.trim() === "") throw new AFSPathError("Meta path cannot be empty", path);
+	if (!path.startsWith("/")) throw new AFSPathError("Meta path must be absolute (start with /)", path);
+	let normalizedPath;
+	try {
+		normalizedPath = validatePath(path.endsWith("/") ? path.slice(0, -1) : path);
+	} catch (e) {
+		if (e instanceof AFSPathError) throw e;
+		throw new AFSPathError(`Invalid meta path: ${path}`, path);
+	}
+	const segments = normalizedPath.split("/");
+	let metaIndex = -1;
+	for (let i = 0; i < segments.length; i++) if (segments[i] === META_SEGMENT) {
+		metaIndex = i;
+		break;
+	}
+	if (metaIndex === -1) throw new AFSPathError(`Path does not contain .meta: ${path}`, path);
+	const nodeSegments = segments.slice(0, metaIndex);
+	const nodePath = nodeSegments.length === 0 ? "/" : `/${nodeSegments.filter(Boolean).join("/")}`;
+	const afterMetaSegments = segments.slice(metaIndex + 1);
+	if (afterMetaSegments.length > 0 && afterMetaSegments[0] === KINDS_SEGMENT) {
+		const kindName = afterMetaSegments.length > 1 ? afterMetaSegments.slice(1).join("/") : null;
+		return {
+			nodePath: nodePath === "" ? "/" : nodePath,
+			resourcePath: null,
+			isKindsPath: true,
+			kindName: kindName || null
+		};
+	}
+	const resourcePath = afterMetaSegments.length > 0 ? afterMetaSegments.join("/") : null;
+	return {
+		nodePath: nodePath === "" ? "/" : nodePath,
+		resourcePath,
+		isKindsPath: false,
+		kindName: null
+	};
+}
+/**
+* Check if a path is a .meta/.kinds path.
+*
+* @param path - Path to check
+* @returns true if the path is a kinds path
+*/
+function isKindsPath(path) {
+	if (!path || !isMetaPath(path)) return false;
+	try {
+		return parseMetaPath(path).isKindsPath;
+	} catch {
+		return false;
+	}
+}
+/**
+* Extract the node path from a meta path.
+*
+* @param metaPath - Meta path
+* @returns Node path (without .meta and after)
+* @throws AFSPathError if path is invalid or not a meta path
+*/
+function getNodePathFromMetaPath(metaPath) {
+	return parseMetaPath(metaPath).nodePath;
+}
+
+//#endregion
+export { KINDS_SEGMENT, META_SEGMENT, getNodePathFromMetaPath, isKindsPath, isMetaPath, parseMetaPath };
+//# sourceMappingURL=path.mjs.map

package/dist/meta/path.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.mjs","names":[],"sources":["../../src/meta/path.ts"],"sourcesContent":["/**\n * Meta Path Utilities for AFS\n *\n * Provides functions to work with .meta virtual paths:\n * - /dir/.meta - directory metadata\n * - /dir/.meta/icon.png - directory meta resource\n * - /dir/file.txt/.meta - file metadata\n * - /.meta/.kinds - provider kinds list\n * - /.meta/.kinds/chamber:project - specific kind\n */\n\nimport { AFSPathError, normalizePath, validatePath } from \"../path.js\";\nimport type { MetaPathInfo } from \"./type.js\";\n\n/** The .meta virtual path segment */\nexport const META_SEGMENT = \".meta\";\n\n/** The .kinds virtual path segment (under .meta) */\nexport const KINDS_SEGMENT = \".kinds\";\n\n/**\n * Check if a path is a .meta virtual path.\n *\n * A path is considered a meta path if it contains \"/.meta\" as a path segment\n * (not just a substring of a filename).\n *\n * @param path - Path to check\n * @returns true if the path is a .meta path\n */\nexport function isMetaPath(path: string): boolean {\n  if (!path) {\n    return false;\n  }\n\n  // Normalize the path to handle // and . and ..\n  // But don't throw for invalid paths, just return false\n  let normalizedPath: string;\n  try {\n    // Handle trailing slash\n    const trimmedPath = path.endsWith(\"/\") ? path.slice(0, -1) : path;\n    if (!trimmedPath.startsWith(\"/\")) {\n      return false;\n    }\n    normalizedPath = normalizePath(trimmedPath);\n  } catch {\n    return false;\n  }\n\n  const segments = normalizedPath.split(\"/\");\n\n  // Check if any segment is exactly .meta\n  for (let i = 0; i < segments.length; i++) {\n    if (segments[i] === META_SEGMENT) {\n      return true;\n    }\n  }\n\n  return false;\n}\n\n/**\n * Parse a .meta virtual path into its components.\n *\n * @param path - Meta path to parse (must be absolute and contain .meta)\n * @returns Parsed MetaPathInfo\n * @throws AFSPathError if path is invalid or not a meta path\n */\nexport function parseMetaPath(path: string): MetaPathInfo {\n  if (!path || path.trim() === \"\") {\n    throw new AFSPathError(\"Meta path cannot be empty\", path);\n  }\n\n  if (!path.startsWith(\"/\")) {\n    throw new AFSPathError(\"Meta path must be absolute (start with /)\", path);\n  }\n\n  // Validate and normalize the path (checks for control characters)\n  let normalizedPath: string;\n  try {\n    const trimmedPath = path.endsWith(\"/\") ? path.slice(0, -1) : path;\n    // validatePath both validates and normalizes\n    normalizedPath = validatePath(trimmedPath);\n  } catch (e) {\n    if (e instanceof AFSPathError) {\n      throw e;\n    }\n    throw new AFSPathError(`Invalid meta path: ${path}`, path);\n  }\n\n  const segments = normalizedPath.split(\"/\");\n\n  // Find the .meta segment index\n  let metaIndex = -1;\n  for (let i = 0; i < segments.length; i++) {\n    if (segments[i] === META_SEGMENT) {\n      metaIndex = i;\n      break;\n    }\n  }\n\n  if (metaIndex === -1) {\n    throw new AFSPathError(`Path does not contain .meta: ${path}`, path);\n  }\n\n  // Node path is everything before .meta\n  const nodeSegments = segments.slice(0, metaIndex);\n  const nodePath = nodeSegments.length === 0 ? \"/\" : `/${nodeSegments.filter(Boolean).join(\"/\")}`;\n\n  // Path after .meta\n  const afterMetaSegments = segments.slice(metaIndex + 1);\n\n  // Check for .kinds path\n  if (afterMetaSegments.length > 0 && afterMetaSegments[0] === KINDS_SEGMENT) {\n    // It's a kinds path\n    const kindName = afterMetaSegments.length > 1 ? afterMetaSegments.slice(1).join(\"/\") : null;\n    return {\n      nodePath: nodePath === \"\" ? \"/\" : nodePath,\n      resourcePath: null,\n      isKindsPath: true,\n      kindName: kindName || null,\n    };\n  }\n\n  // Regular meta path or resource path\n  const resourcePath = afterMetaSegments.length > 0 ? afterMetaSegments.join(\"/\") : null;\n\n  return {\n    nodePath: nodePath === \"\" ? \"/\" : nodePath,\n    resourcePath,\n    isKindsPath: false,\n    kindName: null,\n  };\n}\n\n/**\n * Check if a path is a .meta/.kinds path.\n *\n * @param path - Path to check\n * @returns true if the path is a kinds path\n */\nexport function isKindsPath(path: string): boolean {\n  if (!path || !isMetaPath(path)) {\n    return false;\n  }\n\n  try {\n    const info = parseMetaPath(path);\n    return info.isKindsPath;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Extract the node path from a meta path.\n *\n * @param metaPath - Meta path\n * @returns Node path (without .meta and after)\n * @throws AFSPathError if path is invalid or not a meta path\n */\nexport function getNodePathFromMetaPath(metaPath: string): string {\n  const info = parseMetaPath(metaPath);\n  return info.nodePath;\n}\n"],"mappings":";;;;;;;;;;;;;;AAeA,MAAa,eAAe;;AAG5B,MAAa,gBAAgB;;;;;;;;;;AAW7B,SAAgB,WAAW,MAAuB;AAChD,KAAI,CAAC,KACH,QAAO;CAKT,IAAI;AACJ,KAAI;EAEF,MAAM,cAAc,KAAK,SAAS,IAAI,GAAG,KAAK,MAAM,GAAG,GAAG,GAAG;AAC7D,MAAI,CAAC,YAAY,WAAW,IAAI,CAC9B,QAAO;AAET,mBAAiB,cAAc,YAAY;SACrC;AACN,SAAO;;CAGT,MAAM,WAAW,eAAe,MAAM,IAAI;AAG1C,MAAK,IAAI,IAAI,GAAG,IAAI,SAAS,QAAQ,IACnC,KAAI,SAAS,OAAO,aAClB,QAAO;AAIX,QAAO;;;;;;;;;AAUT,SAAgB,cAAc,MAA4B;AACxD,KAAI,CAAC,QAAQ,KAAK,MAAM,KAAK,GAC3B,OAAM,IAAI,aAAa,6BAA6B,KAAK;AAG3D,KAAI,CAAC,KAAK,WAAW,IAAI,CACvB,OAAM,IAAI,aAAa,6CAA6C,KAAK;CAI3E,IAAI;AACJ,KAAI;AAGF,mBAAiB,aAFG,KAAK,SAAS,IAAI,GAAG,KAAK,MAAM,GAAG,GAAG,GAAG,KAEnB;UACnC,GAAG;AACV,MAAI,aAAa,aACf,OAAM;AAER,QAAM,IAAI,aAAa,sBAAsB,QAAQ,KAAK;;CAG5D,MAAM,WAAW,eAAe,MAAM,IAAI;CAG1C,IAAI,YAAY;AAChB,MAAK,IAAI,IAAI,GAAG,IAAI,SAAS,QAAQ,IACnC,KAAI,SAAS,OAAO,cAAc;AAChC,cAAY;AACZ;;AAIJ,KAAI,cAAc,GAChB,OAAM,IAAI,aAAa,gCAAgC,QAAQ,KAAK;CAItE,MAAM,eAAe,SAAS,MAAM,GAAG,UAAU;CACjD,MAAM,WAAW,aAAa,WAAW,IAAI,MAAM,IAAI,aAAa,OAAO,QAAQ,CAAC,KAAK,IAAI;CAG7F,MAAM,oBAAoB,SAAS,MAAM,YAAY,EAAE;AAGvD,KAAI,kBAAkB,SAAS,KAAK,kBAAkB,OAAO,eAAe;EAE1E,MAAM,WAAW,kBAAkB,SAAS,IAAI,kBAAkB,MAAM,EAAE,CAAC,KAAK,IAAI,GAAG;AACvF,SAAO;GACL,UAAU,aAAa,KAAK,MAAM;GAClC,cAAc;GACd,aAAa;GACb,UAAU,YAAY;GACvB;;CAIH,MAAM,eAAe,kBAAkB,SAAS,IAAI,kBAAkB,KAAK,IAAI,GAAG;AAElF,QAAO;EACL,UAAU,aAAa,KAAK,MAAM;EAClC;EACA,aAAa;EACb,UAAU;EACX;;;;;;;;AASH,SAAgB,YAAY,MAAuB;AACjD,KAAI,CAAC,QAAQ,CAAC,WAAW,KAAK,CAC5B,QAAO;AAGT,KAAI;AAEF,SADa,cAAc,KAAK,CACpB;SACN;AACN,SAAO;;;;;;;;;;AAWX,SAAgB,wBAAwB,UAA0B;AAEhE,QADa,cAAc,SAAS,CACxB"}

package/dist/meta/type.d.cts

@@ -0,0 +1,96 @@
+import { JSONSchema7 } from "../node_modules/.pnpm/@types_json-schema@7.0.15/node_modules/@types/json-schema/index.cjs";
+
+//#region src/meta/type.d.ts
+/**
+ * Constraint for a single node (file or directory) within a Kind.
+ * Supports exact paths, wildcards, and glob patterns.
+ */
+interface NodeConstraint {
+  /**
+   * Node name or path pattern.
+   * - Exact: "src", "README.md"
+   * - Wildcard: "*.md", "*.test.ts"
+   * - Glob: "test/**", "src/**\/*.tsx"
+   */
+  path: string;
+  /** Kind that this node must conform to (optional) */
+  kind?: string;
+  /** Nested constraints for child nodes (recursive) */
+  nodes?: NodesConstraints;
+}
+/**
+ * Constraints for child nodes within a directory.
+ */
+interface NodesConstraints {
+  /** Nodes that must exist */
+  required?: NodeConstraint[];
+  /** Nodes that may exist (validated if present) */
+  optional?: NodeConstraint[];
+  /** Whether to allow nodes not listed in required/optional (default: true) */
+  allowOther?: boolean;
+}
+/**
+ * Kind Schema definition.
+ * Uses JSON Schema for meta validation.
+ */
+interface KindSchema {
+  /** Unique name in format "provider:kind" (e.g., "afs:node", "chamber:project") */
+  name: string;
+  /** Parent kind name for inheritance (single inheritance) */
+  extends?: string;
+  /** Human-readable description */
+  description?: string;
+  /** Meta schema in JSON Schema format */
+  meta?: JSONSchema7;
+  /** Child node structure constraints */
+  nodes?: NodesConstraints;
+}
+/**
+ * Result of validating a node against its Kind Schema.
+ */
+interface ValidationResult {
+  /** Whether validation passed */
+  valid: boolean;
+  /** List of validation errors (empty if valid) */
+  errors: ValidationError[];
+}
+/**
+ * A single validation error.
+ */
+interface ValidationError {
+  /** Path to the invalid property or node */
+  path: string;
+  /** Human-readable error message */
+  message: string;
+  /** Error code for programmatic handling */
+  code?: string;
+  /** Expected value or constraint */
+  expected?: unknown;
+  /** Actual value found */
+  actual?: unknown;
+}
+/**
+ * Parsed information about a .meta virtual path.
+ */
+interface MetaPathInfo {
+  /** Path to the node (without .meta suffix) */
+  nodePath: string;
+  /** Resource path within .meta (e.g., "icon.png"), null for meta itself */
+  resourcePath: string | null;
+  /** Whether this is a .meta/.kinds path */
+  isKindsPath: boolean;
+  /** Specific kind name if accessing .meta/.kinds/{name} */
+  kindName: string | null;
+}
+/**
+ * Result of explain() operation - LLM-friendly node description.
+ */
+interface AFSExplainResult {
+  /** Output format */
+  format: "markdown" | "text";
+  /** Human/LLM readable description */
+  content: string;
+}
+//#endregion
+export { AFSExplainResult, KindSchema, MetaPathInfo, NodeConstraint, NodesConstraints, ValidationError, ValidationResult };
+//# sourceMappingURL=type.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.cts","names":[],"sources":["../../src/meta/type.ts"],"mappings":";;;;;;;UAeiB,cAAA;EAWP;;;AAMV;;;EAVE,IAAA;EAYA;EAVA,IAAA;EAYA;EAVA,KAAA,GAAQ,gBAAA;AAAA;;;AAmBV;UAbiB,gBAAA;;EAEf,QAAA,GAAW,cAAA;EAaX;EAXA,QAAA,GAAW,cAAA;EAeX;EAbA,UAAA;AAAA;;;;;UAOe,UAAA;EAgBgB;EAd/B,IAAA;EAkBuB;EAhBvB,OAAA;EAgBA;EAdA,WAAA;EAcuB;EAZvB,IAAA,GAAO,WAAA;EAkBQ;EAhBf,KAAA,GAAQ,gBAAA;AAAA;;;;UAMO,gBAAA;EAkBf;EAhBA,KAAA;EAkBM;EAhBN,MAAA,EAAQ,eAAA;AAAA;;;;UAMO,eAAA;EAoBf;EAlBA,IAAA;EAsBA;EApBA,OAAA;EAoBQ;EAlBR,IAAA;EAwB+B;EAtB/B,QAAA;EAwBA;EAtBA,MAAA;AAAA;;;;UAMe,YAAA;;EAEf,QAAA;;EAEA,YAAA;;EAEA,WAAA;;EAEA,QAAA;AAAA;;;;UAMe,gBAAA;;EAEf,MAAA;;EAEA,OAAA;AAAA"}

package/dist/meta/type.d.mts

@@ -0,0 +1,96 @@
+import { JSONSchema7 } from "../node_modules/.pnpm/@types_json-schema@7.0.15/node_modules/@types/json-schema/index.mjs";
+
+//#region src/meta/type.d.ts
+/**
+ * Constraint for a single node (file or directory) within a Kind.
+ * Supports exact paths, wildcards, and glob patterns.
+ */
+interface NodeConstraint {
+  /**
+   * Node name or path pattern.
+   * - Exact: "src", "README.md"
+   * - Wildcard: "*.md", "*.test.ts"
+   * - Glob: "test/**", "src/**\/*.tsx"
+   */
+  path: string;
+  /** Kind that this node must conform to (optional) */
+  kind?: string;
+  /** Nested constraints for child nodes (recursive) */
+  nodes?: NodesConstraints;
+}
+/**
+ * Constraints for child nodes within a directory.
+ */
+interface NodesConstraints {
+  /** Nodes that must exist */
+  required?: NodeConstraint[];
+  /** Nodes that may exist (validated if present) */
+  optional?: NodeConstraint[];
+  /** Whether to allow nodes not listed in required/optional (default: true) */
+  allowOther?: boolean;
+}
+/**
+ * Kind Schema definition.
+ * Uses JSON Schema for meta validation.
+ */
+interface KindSchema {
+  /** Unique name in format "provider:kind" (e.g., "afs:node", "chamber:project") */
+  name: string;
+  /** Parent kind name for inheritance (single inheritance) */
+  extends?: string;
+  /** Human-readable description */
+  description?: string;
+  /** Meta schema in JSON Schema format */
+  meta?: JSONSchema7;
+  /** Child node structure constraints */
+  nodes?: NodesConstraints;
+}
+/**
+ * Result of validating a node against its Kind Schema.
+ */
+interface ValidationResult {
+  /** Whether validation passed */
+  valid: boolean;
+  /** List of validation errors (empty if valid) */
+  errors: ValidationError[];
+}
+/**
+ * A single validation error.
+ */
+interface ValidationError {
+  /** Path to the invalid property or node */
+  path: string;
+  /** Human-readable error message */
+  message: string;
+  /** Error code for programmatic handling */
+  code?: string;
+  /** Expected value or constraint */
+  expected?: unknown;
+  /** Actual value found */
+  actual?: unknown;
+}
+/**
+ * Parsed information about a .meta virtual path.
+ */
+interface MetaPathInfo {
+  /** Path to the node (without .meta suffix) */
+  nodePath: string;
+  /** Resource path within .meta (e.g., "icon.png"), null for meta itself */
+  resourcePath: string | null;
+  /** Whether this is a .meta/.kinds path */
+  isKindsPath: boolean;
+  /** Specific kind name if accessing .meta/.kinds/{name} */
+  kindName: string | null;
+}
+/**
+ * Result of explain() operation - LLM-friendly node description.
+ */
+interface AFSExplainResult {
+  /** Output format */
+  format: "markdown" | "text";
+  /** Human/LLM readable description */
+  content: string;
+}
+//#endregion
+export { AFSExplainResult, KindSchema, MetaPathInfo, NodeConstraint, NodesConstraints, ValidationError, ValidationResult };
+//# sourceMappingURL=type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.mts","names":[],"sources":["../../src/meta/type.ts"],"mappings":";;;;;;;UAeiB,cAAA;EAWP;;;AAMV;;;EAVE,IAAA;EAYA;EAVA,IAAA;EAYA;EAVA,KAAA,GAAQ,gBAAA;AAAA;;;AAmBV;UAbiB,gBAAA;;EAEf,QAAA,GAAW,cAAA;EAaX;EAXA,QAAA,GAAW,cAAA;EAeX;EAbA,UAAA;AAAA;;;;;UAOe,UAAA;EAgBgB;EAd/B,IAAA;EAkBuB;EAhBvB,OAAA;EAgBA;EAdA,WAAA;EAcuB;EAZvB,IAAA,GAAO,WAAA;EAkBQ;EAhBf,KAAA,GAAQ,gBAAA;AAAA;;;;UAMO,gBAAA;EAkBf;EAhBA,KAAA;EAkBM;EAhBN,MAAA,EAAQ,eAAA;AAAA;;;;UAMO,eAAA;EAoBf;EAlBA,IAAA;EAsBA;EApBA,OAAA;EAoBQ;EAlBR,IAAA;EAwB+B;EAtB/B,QAAA;EAwBA;EAtBA,MAAA;AAAA;;;;UAMe,YAAA;;EAEf,QAAA;;EAEA,YAAA;;EAEA,WAAA;;EAEA,QAAA;AAAA;;;;UAMe,gBAAA;;EAEf,MAAA;;EAEA,OAAA;AAAA"}

package/dist/meta/validation.cjs

@@ -0,0 +1,77 @@
+let minimatch = require("minimatch");
+
+//#region src/meta/validation.ts
+/**
+* Validation utilities for AFS Meta System.
+*
+* Provides:
+* - Node constraint validation (required/optional nodes, glob patterns)
+* - Validation result types
+*/
+/**
+* Validate a list of node names against NodesConstraints.
+*
+* @param basePath - Base path for error reporting (e.g., "/project")
+* @param nodeNames - List of node names in the directory
+* @param constraints - NodesConstraints to validate against
+* @returns ValidationResult with valid flag and any errors
+*/
+function validateNodes(basePath, nodeNames, constraints) {
+	const errors = [];
+	if (!constraints) return {
+		valid: true,
+		errors: []
+	};
+	const matchedNodes = /* @__PURE__ */ new Set();
+	if (constraints.required) for (const constraint of constraints.required) {
+		const pattern = constraint.path;
+		let found = false;
+		for (const nodeName of nodeNames) if (matchesPattern(nodeName, pattern)) {
+			found = true;
+			matchedNodes.add(nodeName);
+			break;
+		}
+		if (!found) errors.push({
+			path: `${basePath}/${pattern}`,
+			message: `Required node "${pattern}" not found in ${basePath}`,
+			code: "REQUIRED_NODE_MISSING"
+		});
+	}
+	if (constraints.optional) for (const constraint of constraints.optional) {
+		const pattern = constraint.path;
+		for (const nodeName of nodeNames) if (matchesPattern(nodeName, pattern)) matchedNodes.add(nodeName);
+	}
+	if (constraints.allowOther === false) {
+		for (const nodeName of nodeNames) if (!matchedNodes.has(nodeName)) errors.push({
+			path: `${basePath}/${nodeName}`,
+			message: `Unexpected node "${nodeName}" in ${basePath} (allowOther is false)`,
+			code: "UNEXPECTED_NODE"
+		});
+	}
+	return {
+		valid: errors.length === 0,
+		errors
+	};
+}
+/**
+* Check if a node name matches a pattern (supports glob).
+*/
+function matchesPattern(nodeName, pattern) {
+	if (nodeName === pattern) return true;
+	if (pattern.includes("*")) return (0, minimatch.minimatch)(nodeName, pattern, { dot: true });
+	return false;
+}
+/**
+* Combine multiple ValidationResults into one.
+*/
+function combineValidationResults(...results) {
+	const allErrors = results.flatMap((r) => r.errors);
+	return {
+		valid: allErrors.length === 0,
+		errors: allErrors
+	};
+}
+
+//#endregion
+exports.combineValidationResults = combineValidationResults;
+exports.validateNodes = validateNodes;

package/dist/meta/validation.d.cts

@@ -0,0 +1,19 @@
+import { NodesConstraints, ValidationResult } from "./type.cjs";
+
+//#region src/meta/validation.d.ts
+/**
+ * Validate a list of node names against NodesConstraints.
+ *
+ * @param basePath - Base path for error reporting (e.g., "/project")
+ * @param nodeNames - List of node names in the directory
+ * @param constraints - NodesConstraints to validate against
+ * @returns ValidationResult with valid flag and any errors
+ */
+declare function validateNodes(basePath: string, nodeNames: string[], constraints: NodesConstraints | undefined): ValidationResult;
+/**
+ * Combine multiple ValidationResults into one.
+ */
+declare function combineValidationResults(...results: ValidationResult[]): ValidationResult;
+//#endregion
+export { combineValidationResults, validateNodes };
+//# sourceMappingURL=validation.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.cts","names":[],"sources":["../../src/meta/validation.ts"],"mappings":";;;;;;;;;AA6GA;;iBA1FgB,aAAA,CACd,QAAA,UACA,SAAA,YACA,WAAA,EAAa,gBAAA,eACZ,gBAAA;;;;iBAsFa,wBAAA,CAAA,GAA4B,OAAA,EAAS,gBAAA,KAAqB,gBAAA"}

package/dist/meta/validation.d.mts

@@ -0,0 +1,19 @@
+import { NodesConstraints, ValidationResult } from "./type.mjs";
+
+//#region src/meta/validation.d.ts
+/**
+ * Validate a list of node names against NodesConstraints.
+ *
+ * @param basePath - Base path for error reporting (e.g., "/project")
+ * @param nodeNames - List of node names in the directory
+ * @param constraints - NodesConstraints to validate against
+ * @returns ValidationResult with valid flag and any errors
+ */
+declare function validateNodes(basePath: string, nodeNames: string[], constraints: NodesConstraints | undefined): ValidationResult;
+/**
+ * Combine multiple ValidationResults into one.
+ */
+declare function combineValidationResults(...results: ValidationResult[]): ValidationResult;
+//#endregion
+export { combineValidationResults, validateNodes };
+//# sourceMappingURL=validation.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.mts","names":[],"sources":["../../src/meta/validation.ts"],"mappings":";;;;;;;;;AA6GA;;iBA1FgB,aAAA,CACd,QAAA,UACA,SAAA,YACA,WAAA,EAAa,gBAAA,eACZ,gBAAA;;;;iBAsFa,wBAAA,CAAA,GAA4B,OAAA,EAAS,gBAAA,KAAqB,gBAAA"}