@asterdoc/resolvers 0.0.0-stage → 0.9.0

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Paradoc AI, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+**Trademark Notice**: This license does not grant permission to use the trade names, trademarks, service marks, logos, taglines, or product names of Asterdoc, except as required for reasonable and customary use in describing the origin of the Software.

package/README.md

@@ -1,3 +1,158 @@
-# Temporary Holding Version
+<p align="center">
+  <a href="https://asterdoc.com?utm_source=github&utm_medium=resolvers" target="_blank" rel="noopener noreferrer">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://assets.asterdoc.com/asterdoc-logo-400x400-dark.png" type="image/png">
+      <img src="https://assets.asterdoc.com/asterdoc-logo-400x400-dark.png" height="64" alt="Asterdoc logo">
+    </picture>
+  </a>
+  <br />
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">@asterdoc/resolvers</h1>
+
+<div align="center">
+
+[![Asterdoc documentation](https://img.shields.io/badge/Documentation-Asterdoc-red.svg)](https://docs.asterdoc.com?utm_source=github&utm_medium=resolvers)
+[![Follow on Twitter](https://img.shields.io/twitter/follow/asterdoc?style=social)](https://x.com/asterdoc)
+
+</div>
+
+[Asterdoc](https://asterdoc.com?utm_source=github&utm_medium=resolvers) is **documents as code**. It lets developers and AI agents define, validate, and render business documents using typed, composable schemas. This eliminates template drift, broken mappings, and brittle glue code — while giving AI systems a reliable document layer they can safely read, reason over, and generate against in production workflows.
+
+## Package overview
+
+Environment-specific resolvers for Asterdoc. Use these to read layer files, templates, and other assets in your Asterdoc applications.
+
+- 📂 **Filesystem resolver** - Read root-confined local files in Node.js
+- 🌐 **HTTP resolver** - Read files beneath a base URL in any runtime with `fetch`
+- 🧠 **Memory resolver** - Read exact-key text and bytes in any JavaScript environment
+- ✅ **Type-safe** - Full TypeScript support
+- 🔌 **Pluggable** - Implements the `Resolver` interface from `@asterdoc/types`
+
+## Installation
+
+```bash
+npm install @asterdoc/resolvers
+```
+
+## Usage
+
+### Filesystem resolver
+
+Create a resolver to read files from your filesystem:
+
+```typescript
+import { createFsResolver } from "@asterdoc/resolvers/fs";
+
+const resolver = createFsResolver({ root: process.cwd() });
+
+// Read a file relative to root
+const bytes = await resolver.read("/templates/form.md");
+```
+
+Filesystem paths always resolve beneath `root`. A single leading slash means the
+resolver root, not the operating-system root. Parent traversal, outward symlinks,
+backslashes, drive paths, and UNC paths are rejected. Relative roots are anchored
+when the resolver is created. Missing files retain native Node.js error codes;
+policy failures use `ERR_RESOLVER_OUTSIDE_ROOT` or `ERR_RESOLVER_INVALID_PATH`,
+and an empty or non-string `root` throws `ERR_RESOLVER_INVALID_OPTIONS`.
+The root is checked on each read until it is found. A missing root rejects that
+read with Node.js's native `ENOENT` error, and a root created later becomes
+readable.
+
+Artifact paths use forward slashes on every supported host, including Windows.
+Containment assumes the filesystem tree is stable during a read; this resolver
+is not a race-proof sandbox for a concurrently hostile filesystem.
+
+### HTTP resolver
+
+Read files beneath a base URL in any runtime with the Fetch API:
+
+```typescript
+import { createHttpResolver } from "@asterdoc/resolvers/http";
+
+const resolver = createHttpResolver({ baseUrl: "https://example.com/forms/w-9/" });
+
+// Fetches https://example.com/forms/w-9/templates/form.pdf
+const bytes = await resolver.read("/templates/form.pdf");
+```
+
+Paths follow the filesystem rules: forward slashes only, and a single leading
+slash means the base URL, not the origin root. Each segment is percent-encoded.
+A path that resolves outside the base URL rejects with
+`ERR_RESOLVER_OUTSIDE_ROOT`, and one that names the base URL itself with
+`ERR_RESOLVER_INVALID_PATH`, before any request. A 404 rejects with
+`ERR_RESOLVER_NOT_FOUND`, and any other failed status with
+`ERR_RESOLVER_FETCH_FAILED`. Pass `fetch` to add transport policy, such as
+allowed hosts, redirect handling, timeouts, or body size limits. Redirects
+follow the fetch function's own policy. An error thrown by a supplied
+`fetch` passes through unchanged.
+
+### With form rendering
+
+Bind a resolver once, when a form with file-based layers is constructed.
+Every instance you derive from it afterward — every `fill`, every render —
+carries the same resolver:
+
+```typescript
+import { p } from "@asterdoc/sdk";
+import { createFsResolver } from "@asterdoc/resolvers/fs";
+
+const resolver = createFsResolver({ root: "./templates" });
+
+const form = p.form(formSchema, { resolver });
+
+const result = await form
+  .fill({
+    fields: {
+      /* ... */
+    },
+  })
+  .render({
+    layer: "pdf",
+  });
+```
+
+### Using subpath imports
+
+Import each adapter from its environment-specific entrypoint:
+
+```typescript
+import { createFsResolver } from "@asterdoc/resolvers/fs";
+import { createHttpResolver } from "@asterdoc/resolvers/http";
+import { createMemoryResolver } from "@asterdoc/resolvers/memory";
+```
+
+### Memory resolver for testing
+
+For testing and browser environments, use the memory entrypoint. Keys are matched exactly, and binary content (including a Node.js `Buffer`) is copied on input and output. Missing `contents`, or a value that is not a string or `Uint8Array`, throws `ERR_RESOLVER_INVALID_OPTIONS`:
+
+```typescript
+import { createMemoryResolver } from "@asterdoc/resolvers/memory";
+
+const resolver = createMemoryResolver({
+  contents: {
+    "/templates/form.md": "# {{fields.title}}",
+    "/assets/logo.png": myLogoBytes,
+  },
+});
+```
+
+## Changelog
+
+View the [Changelog](https://github.com/asterdoc/asterdoc/blob/main/CHANGELOG.md) for updates.
+
+## Related packages
+
+- [`@asterdoc/sdk`](../sdk) - Asterdoc framework SDK
+- [`@asterdoc/core`](../core) - Core framework behavior
+
+## Contributing
+
+We're open to all community contributions! If you'd like to contribute in any way, please read our [contribution guidelines](https://github.com/asterdoc/asterdoc/blob/main/CONTRIBUTING.md) and [code of conduct](https://github.com/asterdoc/asterdoc/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+This project is licensed under the MIT license.
+
+See [LICENSE](https://github.com/asterdoc/asterdoc/blob/main/LICENSE) for more information.

package/dist/fs.d.ts

@@ -0,0 +1,35 @@
+import { Resolver } from '@asterdoc/types';
+
+/**
+ * Filesystem resolver for Node.js environments.
+ */
+
+/**
+ * Options for creating a filesystem resolver.
+ */
+interface FsResolverOptions {
+    /**
+     * Absolute or current-working-directory-relative path to the root directory.
+     * Relative roots are anchored when the resolver is created.
+     */
+    root: string;
+}
+/**
+ * Create a filesystem resolver for Node.js environments.
+ *
+ * Security: The resolver validates that all resolved paths stay within the root
+ * directory to prevent path traversal attacks.
+ *
+ * @example
+ * ```typescript
+ * import { createFsResolver } from '@asterdoc/resolvers/fs'
+ *
+ * const resolver = createFsResolver({ root: process.cwd() })
+ *
+ * // Read a file relative to root
+ * const bytes = await resolver.read('/templates/form.md')
+ * ```
+ */
+declare function createFsResolver(options: FsResolverOptions): Resolver;
+
+export { type FsResolverOptions, createFsResolver };

package/dist/fs.js

@@ -0,0 +1,71 @@
+// src/fs/index.ts
+import { readFile, realpath } from "fs/promises";
+import { isAbsolute, relative, resolve, sep } from "path";
+
+// src/shared/errors.ts
+function resolverError(code, message, ErrorType = Error) {
+  return Object.assign(new ErrorType(message), { code });
+}
+function invalidOptions(message) {
+  return resolverError("ERR_RESOLVER_INVALID_OPTIONS", message, TypeError);
+}
+function invalidPath(message) {
+  return resolverError("ERR_RESOLVER_INVALID_PATH", message, TypeError);
+}
+function outsideRoot(path) {
+  return resolverError("ERR_RESOLVER_OUTSIDE_ROOT", `Resolver path "${path}" resolves outside the configured root`);
+}
+
+// src/shared/path.ts
+function normalizeRootedPath(path) {
+  if (typeof path !== "string" || path.length === 0) {
+    throw invalidPath("Resolver path must be a non-empty string");
+  }
+  if (path.includes("\0")) {
+    throw invalidPath("Resolver path cannot contain a null byte");
+  }
+  if (path.includes("\\")) {
+    throw invalidPath("Resolver paths must use forward slashes");
+  }
+  if (/^[a-zA-Z]:/.test(path) || path.startsWith("//")) {
+    throw invalidPath("Resolver paths cannot use drive or UNC syntax");
+  }
+  return path.startsWith("/") ? path.slice(1) : path;
+}
+
+// src/fs/index.ts
+function createFsResolver(options) {
+  if (!options || typeof options.root !== "string" || options.root.length === 0) {
+    throw invalidOptions("Resolver root must be a non-empty string");
+  }
+  const rootPath = resolve(options.root);
+  let canonicalRoot;
+  const resolveRoot = () => canonicalRoot ??= realpath(rootPath).catch((error) => {
+    canonicalRoot = void 0;
+    throw error;
+  });
+  return {
+    async read(path) {
+      const logicalPath = normalizeRootedPath(path);
+      const fullPath = resolve(rootPath, logicalPath);
+      if (!isContained(rootPath, fullPath)) {
+        throw outsideRoot(path);
+      }
+      const [resolvedRoot, canonicalPath] = await Promise.all([
+        resolveRoot(),
+        realpath(fullPath)
+      ]);
+      if (!isContained(resolvedRoot, canonicalPath)) {
+        throw outsideRoot(path);
+      }
+      return readFile(canonicalPath);
+    }
+  };
+}
+function isContained(root, candidate) {
+  const fromRoot = relative(root, candidate);
+  return fromRoot === "" || !isAbsolute(fromRoot) && fromRoot !== ".." && !fromRoot.startsWith(`..${sep}`);
+}
+export {
+  createFsResolver
+};

package/dist/http.d.ts

@@ -0,0 +1,45 @@
+import { Resolver } from '@asterdoc/types';
+
+/**
+ * HTTP resolver for any environment with the Fetch API.
+ */
+
+/** Options for creating an HTTP resolver. */
+interface HttpResolverOptions {
+    /**
+     * Absolute `http:` or `https:` URL of the root directory. Every read resolves
+     * beneath it. Its query and fragment are ignored.
+     */
+    baseUrl: string;
+    /**
+     * Fetch function for each read. Defaults to the global `fetch`. Supply one to
+     * add transport policy such as allowed hosts, timeouts, redirects, or body
+     * size limits.
+     */
+    fetch?: (url: string) => Promise<Response>;
+}
+/**
+ * Create a resolver that reads content over HTTP beneath a base URL.
+ *
+ * Paths follow the filesystem resolver's rules: forward slashes only, and a
+ * single leading slash means the base URL, not the origin root. Each path
+ * segment is percent-encoded, so `?`, `#`, and `%` are part of a file name.
+ * Paths that resolve outside the base URL reject with
+ * `ERR_RESOLVER_OUTSIDE_ROOT`, and a path that names the base URL itself with
+ * `ERR_RESOLVER_INVALID_PATH`, before any request. Redirects follow the fetch
+ * function's own policy. A 404 rejects with `ERR_RESOLVER_NOT_FOUND`,
+ * and any other non-2xx status rejects with `ERR_RESOLVER_FETCH_FAILED`.
+ *
+ * @example
+ * ```typescript
+ * import { createHttpResolver } from '@asterdoc/resolvers/http'
+ *
+ * const resolver = createHttpResolver({ baseUrl: 'https://example.com/forms/w-9/' })
+ *
+ * // Fetches https://example.com/forms/w-9/templates/form.pdf
+ * const bytes = await resolver.read('/templates/form.pdf')
+ * ```
+ */
+declare function createHttpResolver(options: HttpResolverOptions): Resolver;
+
+export { type HttpResolverOptions, createHttpResolver };

package/dist/http.js

@@ -0,0 +1,88 @@
+// src/shared/errors.ts
+function resolverError(code, message, ErrorType = Error) {
+  return Object.assign(new ErrorType(message), { code });
+}
+function invalidOptions(message) {
+  return resolverError("ERR_RESOLVER_INVALID_OPTIONS", message, TypeError);
+}
+function invalidPath(message) {
+  return resolverError("ERR_RESOLVER_INVALID_PATH", message, TypeError);
+}
+function outsideRoot(path) {
+  return resolverError("ERR_RESOLVER_OUTSIDE_ROOT", `Resolver path "${path}" resolves outside the configured root`);
+}
+function notFound(path) {
+  return resolverError("ERR_RESOLVER_NOT_FOUND", `Resolver content not found: "${path}"`);
+}
+
+// src/shared/path.ts
+function normalizeRootedPath(path) {
+  if (typeof path !== "string" || path.length === 0) {
+    throw invalidPath("Resolver path must be a non-empty string");
+  }
+  if (path.includes("\0")) {
+    throw invalidPath("Resolver path cannot contain a null byte");
+  }
+  if (path.includes("\\")) {
+    throw invalidPath("Resolver paths must use forward slashes");
+  }
+  if (/^[a-zA-Z]:/.test(path) || path.startsWith("//")) {
+    throw invalidPath("Resolver paths cannot use drive or UNC syntax");
+  }
+  return path.startsWith("/") ? path.slice(1) : path;
+}
+
+// src/http/index.ts
+function createHttpResolver(options) {
+  const root = parseBaseUrl(options?.baseUrl);
+  const fetchFn = options.fetch ?? ((url) => globalThis.fetch(url));
+  if (typeof fetchFn !== "function") {
+    throw invalidOptions("HTTP resolver fetch must be a function");
+  }
+  return {
+    async read(path) {
+      const url = resolveUrl(root, path);
+      const response = await fetchFn(url);
+      if (response.status === 404) throw notFound(path);
+      if (!response.ok) {
+        throw resolverError(
+          "ERR_RESOLVER_FETCH_FAILED",
+          `Resolver fetch failed for "${path}" with status ${response.status}`
+        );
+      }
+      return new Uint8Array(await response.arrayBuffer());
+    }
+  };
+}
+function parseBaseUrl(baseUrl) {
+  if (typeof baseUrl !== "string" || baseUrl.length === 0) {
+    throw invalidOptions("HTTP resolver baseUrl must be a non-empty string");
+  }
+  let root;
+  try {
+    root = new URL(baseUrl);
+  } catch {
+    throw invalidOptions(`HTTP resolver baseUrl must be an absolute URL: "${baseUrl}"`);
+  }
+  if (root.protocol !== "https:" && root.protocol !== "http:") {
+    throw invalidOptions(`HTTP resolver baseUrl must use http or https: "${baseUrl}"`);
+  }
+  root.search = "";
+  root.hash = "";
+  if (!root.pathname.endsWith("/")) root.pathname = `${root.pathname}/`;
+  return root;
+}
+function resolveUrl(root, path) {
+  const encoded = normalizeRootedPath(path).split("/").map((segment) => segment === "." || segment === ".." ? segment : encodeURIComponent(segment)).join("/");
+  const url = new URL(encoded, root);
+  if (url.origin !== root.origin || !url.pathname.startsWith(root.pathname)) {
+    throw outsideRoot(path);
+  }
+  if (url.pathname === root.pathname) {
+    throw invalidPath("Resolver path must name a file beneath the base URL");
+  }
+  return url.toString();
+}
+export {
+  createHttpResolver
+};

package/dist/memory.d.ts

@@ -0,0 +1,20 @@
+import { Resolver } from '@asterdoc/types';
+
+/** Options for creating an in-memory resolver. */
+interface MemoryResolverOptions {
+    /** Exact resolver paths mapped to UTF-8 text or binary content. */
+    contents: Record<string, Uint8Array | string>;
+}
+/**
+ * Create a browser-safe resolver backed by an exact-key content map.
+ *
+ * Binary inputs, including Node.js `Buffer`s, are copied at construction and
+ * every read returns a fresh `Uint8Array` copy, so mutations by either the
+ * caller or a consumer cannot change stored content.
+ *
+ * Throws `ERR_RESOLVER_INVALID_OPTIONS` when `contents` is not an object or a
+ * value is neither a string nor a `Uint8Array`.
+ */
+declare function createMemoryResolver(options: MemoryResolverOptions): Resolver;
+
+export { type MemoryResolverOptions, createMemoryResolver };

package/dist/memory.js

@@ -0,0 +1,39 @@
+// src/shared/errors.ts
+function resolverError(code, message, ErrorType = Error) {
+  return Object.assign(new ErrorType(message), { code });
+}
+function invalidOptions(message) {
+  return resolverError("ERR_RESOLVER_INVALID_OPTIONS", message, TypeError);
+}
+function notFound(path) {
+  return resolverError("ERR_RESOLVER_NOT_FOUND", `Resolver content not found: "${path}"`);
+}
+
+// src/memory/index.ts
+function createMemoryResolver(options) {
+  const supplied = options?.contents;
+  if (typeof supplied !== "object" || supplied === null || Array.isArray(supplied)) {
+    throw invalidOptions("Memory resolver contents must be an object of paths to strings or Uint8Arrays");
+  }
+  const encoder = new TextEncoder();
+  const contents = /* @__PURE__ */ new Map();
+  for (const [path, content] of Object.entries(supplied)) {
+    if (typeof content === "string") {
+      contents.set(path, encoder.encode(content));
+    } else if (content instanceof Uint8Array) {
+      contents.set(path, new Uint8Array(content));
+    } else {
+      throw invalidOptions(`Memory resolver content for "${path}" must be a string or Uint8Array`);
+    }
+  }
+  return {
+    async read(path) {
+      const content = contents.get(path);
+      if (content === void 0) throw notFound(path);
+      return new Uint8Array(content);
+    }
+  };
+}
+export {
+  createMemoryResolver
+};

package/package.json

@@ -1,6 +1,80 @@
 {
   "name": "@asterdoc/resolvers",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.9.0",
+  "description": "Read Asterdoc artifact content from the local filesystem, over HTTP, or from memory.",
+  "type": "module",
+  "exports": {
+    "./fs": {
+      "types": "./dist/fs.d.ts",
+      "import": "./dist/fs.js",
+      "default": "./dist/fs.js"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "import": "./dist/http.js",
+      "default": "./dist/http.js"
+    },
+    "./memory": {
+      "types": "./dist/memory.d.ts",
+      "import": "./dist/memory.js",
+      "default": "./dist/memory.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "asterdoc",
+    "resolvers",
+    "filesystem",
+    "http",
+    "storage",
+    "memory"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Asterdoc",
+    "url": "https://asterdoc.com"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/asterdoc/asterdoc.git",
+    "directory": "packages/resolvers"
+  },
+  "homepage": "https://asterdoc.com",
+  "bugs": {
+    "url": "https://github.com/asterdoc/asterdoc/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@asterdoc/types": "^0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "eslint": "^9.34.0",
+    "tsup": "^8.4.0",
+    "typescript": "5.9.2",
+    "vitest": "^2.1.8",
+    "@asterdoc/typescript-config": "0.1.0",
+    "@asterdoc/eslint-config": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist",
+    "prebuild": "pnpm run clean",
+    "lint": "eslint .",
+    "check-types": "tsc --noEmit",
+    "check": "pnpm lint && pnpm check-types",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
 }