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

package/dist/capabilities/world-mapping.d.mts

@@ -0,0 +1,139 @@
+import { AFSEntry, AFSModule } from "../type.mjs";
+
+//#region src/capabilities/world-mapping.d.ts
+/**
+ * Status information for loaded mapping configuration
+ */
+interface MappingStatus {
+  /** Whether mapping is loaded */
+  loaded: boolean;
+  /** Time when mapping was last loaded */
+  loadedAt?: Date;
+  /** Path to the mapping configuration */
+  mappingPath?: string;
+  /** Whether mapping is successfully compiled */
+  compiled: boolean;
+  /** Error message if loading/compilation failed */
+  error?: string;
+  /** Statistics about the loaded mapping */
+  stats?: {
+    /** Number of route templates */routes: number; /** Number of supported operations */
+    operations: number;
+  };
+}
+/**
+ * Reference to an external system resource
+ */
+interface ExternalRef {
+  /** Type of external system */
+  type: "http" | "graphql" | "mcp-tool" | "custom";
+  /** HTTP: URL, GraphQL: query, MCP: tool name */
+  target: string;
+  /** HTTP method or operation type */
+  method?: string;
+  /** Bound parameters */
+  params?: Record<string, unknown>;
+  /** Headers or metadata */
+  headers?: Record<string, string>;
+}
+/**
+ * Context for projecting external data to AFS entries
+ */
+interface ProjectionContext {
+  /** Original AFS path */
+  path: string;
+  /** Matched path template */
+  template: string;
+  /** Extracted path parameters */
+  pathParams: Record<string, string>;
+  /** Current mapping rule (opaque to core, interpreted by provider) */
+  rule: unknown;
+}
+/**
+ * Types of mutation actions
+ */
+type MutateAction = "create" | "update" | "delete" | "exec";
+/**
+ * Result of a mutation operation
+ */
+interface MutateResult {
+  /** Whether the operation succeeded */
+  success: boolean;
+  /** Result data from the operation */
+  data?: unknown;
+  /** Error message if operation failed */
+  error?: string;
+}
+/**
+ * World Mapping Capability Interface
+ *
+ * Providers implement this interface to support declarative path-to-API mapping.
+ * The mapping DSL defines how AFS paths map to external API calls.
+ *
+ * @example
+ * ```typescript
+ * class AFSGitHub implements AFSModule, AFSWorldMappingCapable {
+ *   async loadMapping(mappingPath: string): Promise<void> {
+ *     // Load and compile mapping from AFS
+ *   }
+ *
+ *   resolve(path: string): ExternalRef | null {
+ *     // Match path against compiled routes
+ *   }
+ *
+ *   project(data: unknown, ctx: ProjectionContext): AFSEntry[] {
+ *     // Transform API response to AFS entries
+ *   }
+ * }
+ * ```
+ */
+interface AFSWorldMappingCapable {
+  /**
+   * Load mapping configuration from AFS path
+   * @param mappingPath AFS path to mapping configuration file or directory
+   */
+  loadMapping(mappingPath: string): Promise<void>;
+  /**
+   * Reload mapping configuration (hot-reload)
+   * Should rollback to previous valid configuration on failure
+   */
+  reloadMapping(): Promise<void>;
+  /**
+   * Get current mapping status
+   */
+  getMappingStatus(): MappingStatus;
+  /**
+   * Resolve AFS path to external reference
+   * @param path AFS internal path
+   * @returns External system reference, or null if path doesn't match any route
+   */
+  resolve(path: string): ExternalRef | null;
+  /**
+   * Project external data to AFS entries
+   * @param externalData Data returned from external API
+   * @param context Resolution context (path, template, params, rule)
+   * @returns Array of AFS entries
+   */
+  project(externalData: unknown, context: ProjectionContext): AFSEntry[];
+  /**
+   * Execute mutation operation
+   * @param path AFS path
+   * @param action Mutation type
+   * @param payload Operation parameters
+   */
+  mutate(path: string, action: MutateAction, payload: unknown): Promise<MutateResult>;
+}
+/**
+ * Type guard to check if a module implements World Mapping capability
+ *
+ * @example
+ * ```typescript
+ * if (isWorldMappingCapable(provider)) {
+ *   await provider.loadMapping("/config/mapping/github.yaml");
+ * }
+ * ```
+ */
+declare function isWorldMappingCapable(module: AFSModule | null | undefined): module is AFSModule & AFSWorldMappingCapable;
+//#endregion
+export { AFSWorldMappingCapable, ExternalRef, MappingStatus, MutateAction, MutateResult, ProjectionContext, isWorldMappingCapable };
+//# sourceMappingURL=world-mapping.d.mts.map

package/dist/capabilities/world-mapping.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-mapping.d.mts","names":[],"sources":["../../src/capabilities/world-mapping.ts"],"mappings":";;;;;;UAkBiB,aAAA;EAgBH;EAdZ,MAAA;EAqB0B;EAnB1B,QAAA,GAAW,IAAA;EA6BK;EA3BhB,WAAA;EAqBA;EAnBA,QAAA;EAuBA;EArBA,KAAA;EAuBA;EArBA,KAAA;IAqBgB,gCAnBd,MAAA,UAyBa;IAvBb,UAAA;EAAA;AAAA;;;;UAOa,WAAA;EAwBf;EAtBA,IAAA;EAsBI;EApBJ,MAAA;EA0BsB;EAxBtB,MAAA;EAwBsB;EAtBtB,MAAA,GAAS,MAAA;EA2BM;EAzBf,OAAA,GAAU,MAAA;AAAA;;;;UAMK,iBAAA;EAyBV;EAvBL,IAAA;EAiDe;EA/Cf,QAAA;;EAEA,UAAA,EAAY,MAAA;EAwDK;EAtDjB,IAAA;AAAA;;;;KAMU,YAAA;;;;UAKK,YAAA;EAqCH;EAnCZ,OAAA;EAyCA;EAvCA,IAAA;EA4CA;EA1CA,KAAA;AAAA;;;;;;;;;;;;;;;;;AA8EF;;;;;;;UApDiB,sBAAA;EAqDP;;;;EAhDR,WAAA,CAAY,WAAA,WAAsB,OAAA;EAiDW;;;;EA3C7C,aAAA,IAAiB,OAAA;;;;EAKjB,gBAAA,IAAoB,aAAA;;;;;;EAOpB,OAAA,CAAQ,IAAA,WAAe,WAAA;;;;;;;EAQvB,OAAA,CAAQ,YAAA,WAAuB,OAAA,EAAS,iBAAA,GAAoB,QAAA;;;;;;;EAQ5D,MAAA,CAAO,IAAA,UAAc,MAAA,EAAQ,YAAA,EAAc,OAAA,YAAmB,OAAA,CAAQ,YAAA;AAAA;;;;;;;;;;;iBAaxD,qBAAA,CACd,MAAA,EAAQ,SAAA,sBACP,MAAA,IAAU,SAAA,GAAY,sBAAA"}

package/dist/capabilities/world-mapping.mjs

@@ -0,0 +1,20 @@
+//#region src/capabilities/world-mapping.ts
+/**
+* Type guard to check if a module implements World Mapping capability
+*
+* @example
+* ```typescript
+* if (isWorldMappingCapable(provider)) {
+*   await provider.loadMapping("/config/mapping/github.yaml");
+* }
+* ```
+*/
+function isWorldMappingCapable(module) {
+	if (!module) return false;
+	const m = module;
+	return typeof m.loadMapping === "function" && typeof m.reloadMapping === "function" && typeof m.getMappingStatus === "function" && typeof m.resolve === "function" && typeof m.project === "function" && typeof m.mutate === "function";
+}
+
+//#endregion
+export { isWorldMappingCapable };
+//# sourceMappingURL=world-mapping.mjs.map

package/dist/capabilities/world-mapping.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-mapping.mjs","names":[],"sources":["../../src/capabilities/world-mapping.ts"],"sourcesContent":["/**\n * World Mapping Capability\n *\n * Provider capability for declarative path-to-API mapping.\n * DSL is stored as data in AFS, execution happens at the provider boundary.\n *\n * Core principle:\n * - DSL is data (living in AFS)\n * - Execution is capability (living in provider)\n *\n * @see intent/specs/world-mapping-capability.md\n */\n\nimport type { AFSEntry, AFSModule } from \"../type.js\";\n\n/**\n * Status information for loaded mapping configuration\n */\nexport interface MappingStatus {\n  /** Whether mapping is loaded */\n  loaded: boolean;\n  /** Time when mapping was last loaded */\n  loadedAt?: Date;\n  /** Path to the mapping configuration */\n  mappingPath?: string;\n  /** Whether mapping is successfully compiled */\n  compiled: boolean;\n  /** Error message if loading/compilation failed */\n  error?: string;\n  /** Statistics about the loaded mapping */\n  stats?: {\n    /** Number of route templates */\n    routes: number;\n    /** Number of supported operations */\n    operations: number;\n  };\n}\n\n/**\n * Reference to an external system resource\n */\nexport interface ExternalRef {\n  /** Type of external system */\n  type: \"http\" | \"graphql\" | \"mcp-tool\" | \"custom\";\n  /** HTTP: URL, GraphQL: query, MCP: tool name */\n  target: string;\n  /** HTTP method or operation type */\n  method?: string;\n  /** Bound parameters */\n  params?: Record<string, unknown>;\n  /** Headers or metadata */\n  headers?: Record<string, string>;\n}\n\n/**\n * Context for projecting external data to AFS entries\n */\nexport interface ProjectionContext {\n  /** Original AFS path */\n  path: string;\n  /** Matched path template */\n  template: string;\n  /** Extracted path parameters */\n  pathParams: Record<string, string>;\n  /** Current mapping rule (opaque to core, interpreted by provider) */\n  rule: unknown;\n}\n\n/**\n * Types of mutation actions\n */\nexport type MutateAction = \"create\" | \"update\" | \"delete\" | \"exec\";\n\n/**\n * Result of a mutation operation\n */\nexport interface MutateResult {\n  /** Whether the operation succeeded */\n  success: boolean;\n  /** Result data from the operation */\n  data?: unknown;\n  /** Error message if operation failed */\n  error?: string;\n}\n\n/**\n * World Mapping Capability Interface\n *\n * Providers implement this interface to support declarative path-to-API mapping.\n * The mapping DSL defines how AFS paths map to external API calls.\n *\n * @example\n * ```typescript\n * class AFSGitHub implements AFSModule, AFSWorldMappingCapable {\n *   async loadMapping(mappingPath: string): Promise<void> {\n *     // Load and compile mapping from AFS\n *   }\n *\n *   resolve(path: string): ExternalRef | null {\n *     // Match path against compiled routes\n *   }\n *\n *   project(data: unknown, ctx: ProjectionContext): AFSEntry[] {\n *     // Transform API response to AFS entries\n *   }\n * }\n * ```\n */\nexport interface AFSWorldMappingCapable {\n  /**\n   * Load mapping configuration from AFS path\n   * @param mappingPath AFS path to mapping configuration file or directory\n   */\n  loadMapping(mappingPath: string): Promise<void>;\n\n  /**\n   * Reload mapping configuration (hot-reload)\n   * Should rollback to previous valid configuration on failure\n   */\n  reloadMapping(): Promise<void>;\n\n  /**\n   * Get current mapping status\n   */\n  getMappingStatus(): MappingStatus;\n\n  /**\n   * Resolve AFS path to external reference\n   * @param path AFS internal path\n   * @returns External system reference, or null if path doesn't match any route\n   */\n  resolve(path: string): ExternalRef | null;\n\n  /**\n   * Project external data to AFS entries\n   * @param externalData Data returned from external API\n   * @param context Resolution context (path, template, params, rule)\n   * @returns Array of AFS entries\n   */\n  project(externalData: unknown, context: ProjectionContext): AFSEntry[];\n\n  /**\n   * Execute mutation operation\n   * @param path AFS path\n   * @param action Mutation type\n   * @param payload Operation parameters\n   */\n  mutate(path: string, action: MutateAction, payload: unknown): Promise<MutateResult>;\n}\n\n/**\n * Type guard to check if a module implements World Mapping capability\n *\n * @example\n * ```typescript\n * if (isWorldMappingCapable(provider)) {\n *   await provider.loadMapping(\"/config/mapping/github.yaml\");\n * }\n * ```\n */\nexport function isWorldMappingCapable(\n  module: AFSModule | null | undefined,\n): module is AFSModule & AFSWorldMappingCapable {\n  if (!module) return false;\n\n  const m = module as unknown as Partial<AFSWorldMappingCapable>;\n  return (\n    typeof m.loadMapping === \"function\" &&\n    typeof m.reloadMapping === \"function\" &&\n    typeof m.getMappingStatus === \"function\" &&\n    typeof m.resolve === \"function\" &&\n    typeof m.project === \"function\" &&\n    typeof m.mutate === \"function\"\n  );\n}\n"],"mappings":";;;;;;;;;;;AAgKA,SAAgB,sBACd,QAC8C;AAC9C,KAAI,CAAC,OAAQ,QAAO;CAEpB,MAAM,IAAI;AACV,QACE,OAAO,EAAE,gBAAgB,cACzB,OAAO,EAAE,kBAAkB,cAC3B,OAAO,EAAE,qBAAqB,cAC9B,OAAO,EAAE,YAAY,cACrB,OAAO,EAAE,YAAY,cACrB,OAAO,EAAE,WAAW"}

package/dist/error.cjs

@@ -0,0 +1,63 @@
+
+//#region src/error.ts
+/**
+* Base error class for all AFS errors.
+*/
+var AFSError = class extends Error {
+	code;
+	constructor(message, code) {
+		super(message);
+		this.name = "AFSError";
+		this.code = code;
+	}
+};
+/**
+* Error thrown when attempting write operations on a readonly AFS or module.
+*/
+var AFSReadonlyError = class extends AFSError {
+	constructor(message) {
+		super(message, "AFS_READONLY");
+		this.name = "AFSReadonlyError";
+	}
+};
+/**
+* Error thrown when a path does not exist.
+*/
+var AFSNotFoundError = class extends AFSError {
+	path;
+	constructor(path, message) {
+		super(message || `Path not found: ${path}`, "AFS_NOT_FOUND");
+		this.name = "AFSNotFoundError";
+		this.path = path;
+	}
+};
+/**
+* Error thrown when input validation fails.
+* Used by AFS Core to validate exec inputs against inputSchema.
+*/
+var AFSValidationError = class extends AFSError {
+	constructor(message) {
+		super(message, "AFS_VALIDATION_ERROR");
+		this.name = "AFSValidationError";
+	}
+};
+/**
+* Error thrown when provider mount check fails.
+*/
+var AFSMountError = class extends AFSError {
+	providerName;
+	step;
+	constructor(providerName, step, message) {
+		super(`Mount check failed for ${providerName} at ${step}: ${message}`, "AFS_MOUNT_FAILED");
+		this.name = "AFSMountError";
+		this.providerName = providerName;
+		this.step = step;
+	}
+};
+
+//#endregion
+exports.AFSError = AFSError;
+exports.AFSMountError = AFSMountError;
+exports.AFSNotFoundError = AFSNotFoundError;
+exports.AFSReadonlyError = AFSReadonlyError;
+exports.AFSValidationError = AFSValidationError;

package/dist/error.d.cts

@@ -0,0 +1,39 @@
+//#region src/error.d.ts
+/**
+ * Base error class for all AFS errors.
+ */
+declare class AFSError extends Error {
+  readonly code: string;
+  constructor(message: string, code: string);
+}
+/**
+ * Error thrown when attempting write operations on a readonly AFS or module.
+ */
+declare class AFSReadonlyError extends AFSError {
+  constructor(message: string);
+}
+/**
+ * Error thrown when a path does not exist.
+ */
+declare class AFSNotFoundError extends AFSError {
+  readonly path: string;
+  constructor(path: string, message?: string);
+}
+/**
+ * Error thrown when input validation fails.
+ * Used by AFS Core to validate exec inputs against inputSchema.
+ */
+declare class AFSValidationError extends AFSError {
+  constructor(message: string);
+}
+/**
+ * Error thrown when provider mount check fails.
+ */
+declare class AFSMountError extends AFSError {
+  readonly providerName: string;
+  readonly step: "stat" | "read" | "list";
+  constructor(providerName: string, step: AFSMountError["step"], message: string);
+}
+//#endregion
+export { AFSError, AFSMountError, AFSNotFoundError, AFSReadonlyError, AFSValidationError };
+//# sourceMappingURL=error.d.cts.map

package/dist/error.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.cts","names":[],"sources":["../src/error.ts"],"mappings":";;AAGA;;cAAa,QAAA,SAAiB,KAAA;EAAA,SACnB,IAAA;cAEG,OAAA,UAAiB,IAAA;AAAA;;;;cAUlB,gBAAA,SAAyB,QAAA;cACxB,OAAA;AAAA;;;;cASD,gBAAA,SAAyB,QAAA;EAAA,SAC3B,IAAA;cAEG,IAAA,UAAc,OAAA;AAAA;;AAH5B;;;cAca,kBAAA,SAA2B,QAAA;cAC1B,OAAA;AAAA;;;;cASD,aAAA,SAAsB,QAAA;EAAA,SACxB,YAAA;EAAA,SACA,IAAA;cAEG,YAAA,UAAsB,IAAA,EAAM,aAAA,UAAuB,OAAA;AAAA"}

package/dist/error.d.mts

@@ -0,0 +1,39 @@
+//#region src/error.d.ts
+/**
+ * Base error class for all AFS errors.
+ */
+declare class AFSError extends Error {
+  readonly code: string;
+  constructor(message: string, code: string);
+}
+/**
+ * Error thrown when attempting write operations on a readonly AFS or module.
+ */
+declare class AFSReadonlyError extends AFSError {
+  constructor(message: string);
+}
+/**
+ * Error thrown when a path does not exist.
+ */
+declare class AFSNotFoundError extends AFSError {
+  readonly path: string;
+  constructor(path: string, message?: string);
+}
+/**
+ * Error thrown when input validation fails.
+ * Used by AFS Core to validate exec inputs against inputSchema.
+ */
+declare class AFSValidationError extends AFSError {
+  constructor(message: string);
+}
+/**
+ * Error thrown when provider mount check fails.
+ */
+declare class AFSMountError extends AFSError {
+  readonly providerName: string;
+  readonly step: "stat" | "read" | "list";
+  constructor(providerName: string, step: AFSMountError["step"], message: string);
+}
+//#endregion
+export { AFSError, AFSMountError, AFSNotFoundError, AFSReadonlyError, AFSValidationError };
+//# sourceMappingURL=error.d.mts.map

package/dist/error.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.mts","names":[],"sources":["../src/error.ts"],"mappings":";;AAGA;;cAAa,QAAA,SAAiB,KAAA;EAAA,SACnB,IAAA;cAEG,OAAA,UAAiB,IAAA;AAAA;;;;cAUlB,gBAAA,SAAyB,QAAA;cACxB,OAAA;AAAA;;;;cASD,gBAAA,SAAyB,QAAA;EAAA,SAC3B,IAAA;cAEG,IAAA,UAAc,OAAA;AAAA;;AAH5B;;;cAca,kBAAA,SAA2B,QAAA;cAC1B,OAAA;AAAA;;;;cASD,aAAA,SAAsB,QAAA;EAAA,SACxB,YAAA;EAAA,SACA,IAAA;cAEG,YAAA,UAAsB,IAAA,EAAM,aAAA,UAAuB,OAAA;AAAA"}

package/dist/error.mjs

@@ -0,0 +1,59 @@
+//#region src/error.ts
+/**
+* Base error class for all AFS errors.
+*/
+var AFSError = class extends Error {
+	code;
+	constructor(message, code) {
+		super(message);
+		this.name = "AFSError";
+		this.code = code;
+	}
+};
+/**
+* Error thrown when attempting write operations on a readonly AFS or module.
+*/
+var AFSReadonlyError = class extends AFSError {
+	constructor(message) {
+		super(message, "AFS_READONLY");
+		this.name = "AFSReadonlyError";
+	}
+};
+/**
+* Error thrown when a path does not exist.
+*/
+var AFSNotFoundError = class extends AFSError {
+	path;
+	constructor(path, message) {
+		super(message || `Path not found: ${path}`, "AFS_NOT_FOUND");
+		this.name = "AFSNotFoundError";
+		this.path = path;
+	}
+};
+/**
+* Error thrown when input validation fails.
+* Used by AFS Core to validate exec inputs against inputSchema.
+*/
+var AFSValidationError = class extends AFSError {
+	constructor(message) {
+		super(message, "AFS_VALIDATION_ERROR");
+		this.name = "AFSValidationError";
+	}
+};
+/**
+* Error thrown when provider mount check fails.
+*/
+var AFSMountError = class extends AFSError {
+	providerName;
+	step;
+	constructor(providerName, step, message) {
+		super(`Mount check failed for ${providerName} at ${step}: ${message}`, "AFS_MOUNT_FAILED");
+		this.name = "AFSMountError";
+		this.providerName = providerName;
+		this.step = step;
+	}
+};
+
+//#endregion
+export { AFSError, AFSMountError, AFSNotFoundError, AFSReadonlyError, AFSValidationError };
+//# sourceMappingURL=error.mjs.map

package/dist/error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.mjs","names":[],"sources":["../src/error.ts"],"sourcesContent":["/**\n * Base error class for all AFS errors.\n */\nexport class AFSError extends Error {\n  readonly code: string;\n\n  constructor(message: string, code: string) {\n    super(message);\n    this.name = \"AFSError\";\n    this.code = code;\n  }\n}\n\n/**\n * Error thrown when attempting write operations on a readonly AFS or module.\n */\nexport class AFSReadonlyError extends AFSError {\n  constructor(message: string) {\n    super(message, \"AFS_READONLY\");\n    this.name = \"AFSReadonlyError\";\n  }\n}\n\n/**\n * Error thrown when a path does not exist.\n */\nexport class AFSNotFoundError extends AFSError {\n  readonly path: string;\n\n  constructor(path: string, message?: string) {\n    super(message || `Path not found: ${path}`, \"AFS_NOT_FOUND\");\n    this.name = \"AFSNotFoundError\";\n    this.path = path;\n  }\n}\n\n/**\n * Error thrown when input validation fails.\n * Used by AFS Core to validate exec inputs against inputSchema.\n */\nexport class AFSValidationError extends AFSError {\n  constructor(message: string) {\n    super(message, \"AFS_VALIDATION_ERROR\");\n    this.name = \"AFSValidationError\";\n  }\n}\n\n/**\n * Error thrown when provider mount check fails.\n */\nexport class AFSMountError extends AFSError {\n  readonly providerName: string;\n  readonly step: \"stat\" | \"read\" | \"list\";\n\n  constructor(providerName: string, step: AFSMountError[\"step\"], message: string) {\n    super(`Mount check failed for ${providerName} at ${step}: ${message}`, \"AFS_MOUNT_FAILED\");\n    this.name = \"AFSMountError\";\n    this.providerName = providerName;\n    this.step = step;\n  }\n}\n"],"mappings":";;;;AAGA,IAAa,WAAb,cAA8B,MAAM;CAClC,AAAS;CAET,YAAY,SAAiB,MAAc;AACzC,QAAM,QAAQ;AACd,OAAK,OAAO;AACZ,OAAK,OAAO;;;;;;AAOhB,IAAa,mBAAb,cAAsC,SAAS;CAC7C,YAAY,SAAiB;AAC3B,QAAM,SAAS,eAAe;AAC9B,OAAK,OAAO;;;;;;AAOhB,IAAa,mBAAb,cAAsC,SAAS;CAC7C,AAAS;CAET,YAAY,MAAc,SAAkB;AAC1C,QAAM,WAAW,mBAAmB,QAAQ,gBAAgB;AAC5D,OAAK,OAAO;AACZ,OAAK,OAAO;;;;;;;AAQhB,IAAa,qBAAb,cAAwC,SAAS;CAC/C,YAAY,SAAiB;AAC3B,QAAM,SAAS,uBAAuB;AACtC,OAAK,OAAO;;;;;;AAOhB,IAAa,gBAAb,cAAmC,SAAS;CAC1C,AAAS;CACT,AAAS;CAET,YAAY,cAAsB,MAA6B,SAAiB;AAC9E,QAAM,0BAA0B,aAAa,MAAM,KAAK,IAAI,WAAW,mBAAmB;AAC1F,OAAK,OAAO;AACZ,OAAK,eAAe;AACpB,OAAK,OAAO"}