veryfront 0.1.215 → 0.1.217

package/src/src/extensions/capabilities.ts

@@ -0,0 +1,97 @@
+/**
+ * Capability audit logging and Deno permission mapping.
+ *
+ * @module extensions/capabilities
+ */
+
+import type { Capability, ExtensionLogger } from "./types.js";
+
+/**
+ * Format capabilities as human-readable strings for logging.
+ */
+export function formatCapabilities(capabilities: Capability[]): string[] {
+  return capabilities.map((cap) => {
+    if (cap.type === "contract") {
+      return `contract: ${cap.name as string}`;
+    }
+
+    const { type, ...rest } = cap;
+    const extras = Object.keys(rest);
+    if (extras.length === 0) return type;
+
+    const details = extras
+      .map((key) => `${key}: ${JSON.stringify(rest[key])}`)
+      .join(", ");
+    return `${type} (${details})`;
+  });
+}
+
+interface PermissionMapping {
+  flag: string;
+  scopeKey?: string;
+  /** Resolve scopes from the full capability (overrides scopeKey when present). */
+  resolveScopes?: (cap: Capability) => string[];
+}
+
+const DENO_PERMISSION_MAP: Record<string, PermissionMapping> = {
+  "fs:read": { flag: "--allow-read", scopeKey: "paths" },
+  "fs:write": { flag: "--allow-write", scopeKey: "paths" },
+  "net:outbound": { flag: "--allow-net", scopeKey: "hosts" },
+  "net:listen": {
+    flag: "--allow-net",
+    resolveScopes: (cap) => {
+      const ports = cap.ports as (string | number)[] | undefined;
+      if (!ports || ports.length === 0) return [];
+      const host = (cap.host as string) || "localhost";
+      return ports.map((p) => `${host}:${p}`);
+    },
+  },
+  "env:read": { flag: "--allow-env", scopeKey: "keys" },
+  "process:spawn": { flag: "--allow-run", scopeKey: "commands" },
+  "native:ffi": { flag: "--allow-ffi" },
+};
+
+/**
+ * Map capabilities to Deno CLI permission flags.
+ * Skips non-system capabilities (e.g., "contract").
+ */
+export function mapToDenoPermissions(capabilities: Capability[]): string[] {
+  const seen = new Set<string>();
+  const flags: string[] = [];
+
+  for (const cap of capabilities) {
+    const mapping = DENO_PERMISSION_MAP[cap.type];
+    if (!mapping) continue;
+
+    let flag = mapping.flag;
+    const scopes = mapping.resolveScopes
+      ? mapping.resolveScopes(cap)
+      : mapping.scopeKey
+      ? (cap[mapping.scopeKey] as string[] | undefined) ?? []
+      : [];
+    if (scopes.length > 0) {
+      flag = `${flag}=${scopes.join(",")}`;
+    }
+
+    if (!seen.has(flag)) {
+      seen.add(flag);
+      flags.push(flag);
+    }
+  }
+
+  return flags;
+}
+
+/**
+ * Log capabilities for a named extension at startup.
+ */
+export function auditCapabilities(
+  extensionName: string,
+  capabilities: Capability[],
+  logger: ExtensionLogger,
+): void {
+  if (capabilities.length === 0) return;
+
+  const lines = formatCapabilities(capabilities);
+  logger.info(`Extension "${extensionName}" declares capabilities:`, ...lines);
+}

package/src/src/extensions/contracts.ts

@@ -0,0 +1,36 @@
+/**
+ * Contract registry — runtime resolution of extension-provided implementations.
+ *
+ * @module extensions/contracts
+ */
+
+import { MISSING_EXTENSION_ERROR } from "./errors.js";
+import { getRecommendation } from "./recommendations.js";
+
+const contracts = new Map<string, unknown>();
+
+export function resolve<T>(name: string): T {
+  const impl = contracts.get(name);
+  if (impl === undefined) {
+    const recommendation = getRecommendation(name);
+    throw MISSING_EXTENSION_ERROR.create({
+      message: `Missing extension for contract "${name}"${
+        recommendation ? `. Recommended: ${recommendation}` : ""
+      }`,
+      detail: recommendation ? `Install it with: deno add ${recommendation}` : undefined,
+    });
+  }
+  return impl as T;
+}
+
+export function tryResolve<T>(name: string): T | undefined {
+  return contracts.get(name) as T | undefined;
+}
+
+export function register<T>(name: string, impl: T): void {
+  contracts.set(name, impl);
+}
+
+export function reset(): void {
+  contracts.clear();
+}

package/src/src/extensions/discovery.ts

@@ -0,0 +1,221 @@
+/**
+ * Multi-source extension discovery.
+ *
+ * Discovers extensions from four sources with priority:
+ *   config > package > project > local-file
+ *
+ * @module extensions/discovery
+ */
+import * as dntShim from "../../_dnt.shims.js";
+
+
+import { join } from "../../deps/jsr.io/@std/path/1.1.4/mod.js";
+import type { Capability, ResolvedExtension } from "./types.js";
+
+/**
+ * Metadata extracted from a package.json that declares itself
+ * as a veryfront extension.
+ */
+export interface PackageMetadata {
+  isExtension: true;
+  capabilities: Capability[];
+}
+
+function isCapability(value: unknown): value is Capability {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const cap = value as Record<string, unknown>;
+  return typeof cap.type === "string" && cap.type.length > 0;
+}
+
+/**
+ * Parse veryfront extension metadata from a package.json-like object.
+ *
+ * Returns `PackageMetadata` when the package declares
+ * `veryfront.extension: true`, otherwise `undefined`. Malformed capability
+ * entries are filtered out; the caller receives only valid shapes.
+ */
+export function parsePackageMetadata(
+  pkg: Record<string, unknown>,
+): PackageMetadata | undefined {
+  const vf = pkg.veryfront;
+  if (
+    vf === null || vf === undefined || typeof vf !== "object" ||
+    Array.isArray(vf)
+  ) {
+    return undefined;
+  }
+
+  const meta = vf as Record<string, unknown>;
+  if (meta.extension !== true) {
+    return undefined;
+  }
+
+  const capabilities: Capability[] = Array.isArray(meta.capabilities)
+    ? meta.capabilities.filter(isCapability)
+    : [];
+
+  return { isExtension: true, capabilities };
+}
+
+/**
+ * Merge extensions from all four sources in priority order.
+ *
+ * Priority (highest first): config > package > project > local-file.
+ * Duplicates are resolved by keeping the highest-priority entry.
+ * Disable directives (`{ name, enabled: false }`) remove matching
+ * extensions regardless of source.
+ */
+export function mergeExtensions(
+  config: ResolvedExtension[],
+  packages: ResolvedExtension[],
+  project: ResolvedExtension[],
+  local: ResolvedExtension[],
+  disableDirectives?: Array<{ name: string; enabled: false }>,
+): ResolvedExtension[] {
+  const disabledNames = new Set(
+    (disableDirectives ?? []).map((d) => d.name),
+  );
+
+  const seen = new Map<string, ResolvedExtension>();
+
+  // Process sources in priority order -- first write wins.
+  const ordered: ResolvedExtension[] = [
+    ...config,
+    ...packages,
+    ...project,
+    ...local,
+  ];
+
+  for (const resolved of ordered) {
+    const name = resolved.extension.name;
+    if (disabledNames.has(name)) continue;
+    if (!seen.has(name)) {
+      seen.set(name, resolved);
+    }
+  }
+
+  return [...seen.values()];
+}
+
+// ---------------------------------------------------------------------------
+// Filesystem discovery helpers
+// ---------------------------------------------------------------------------
+
+async function readDir(path: string): Promise<dntShim.Deno.DirEntry[]> {
+  try {
+    const entries: dntShim.Deno.DirEntry[] = [];
+    for await (const entry of dntShim.Deno.readDir(path)) {
+      entries.push(entry);
+    }
+    return entries;
+  } catch (err) {
+    if (err instanceof dntShim.Deno.errors.NotFound) return [];
+    throw err;
+  }
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await dntShim.Deno.stat(path);
+    return true;
+  } catch (err) {
+    if (err instanceof dntShim.Deno.errors.NotFound) return false;
+    throw err;
+  }
+}
+
+/**
+ * Scan `node_modules` (including `@scoped` packages) for packages
+ * that declare veryfront extension metadata in their `package.json`.
+ */
+export async function discoverPackageExtensions(
+  baseDir: string,
+): Promise<Array<{ packageName: string; metadata: PackageMetadata }>> {
+  const nmDir = join(baseDir, "node_modules");
+  const results: Array<{ packageName: string; metadata: PackageMetadata }> = [];
+  const entries = await readDir(nmDir);
+
+  for (const entry of entries) {
+    // Accept symlinks so pnpm-style node_modules layouts are discovered.
+    if (!entry.isDirectory && !entry.isSymlink) continue;
+
+    if (entry.name.startsWith("@")) {
+      // Scoped packages -- iterate one level deeper.
+      const scopeDir = join(nmDir, entry.name);
+      const scopeEntries = await readDir(scopeDir);
+      for (const scopeEntry of scopeEntries) {
+        if (!scopeEntry.isDirectory && !scopeEntry.isSymlink) continue;
+        const pkgName = `${entry.name}/${scopeEntry.name}`;
+        const meta = await tryReadPackageMeta(
+          join(scopeDir, scopeEntry.name),
+        );
+        if (meta) results.push({ packageName: pkgName, metadata: meta });
+      }
+    } else {
+      const meta = await tryReadPackageMeta(join(nmDir, entry.name));
+      if (meta) results.push({ packageName: entry.name, metadata: meta });
+    }
+  }
+
+  return results;
+}
+
+async function tryReadPackageMeta(
+  pkgDir: string,
+): Promise<PackageMetadata | undefined> {
+  let raw: string;
+  try {
+    raw = await dntShim.Deno.readTextFile(join(pkgDir, "package.json"));
+  } catch (err) {
+    if (err instanceof dntShim.Deno.errors.NotFound) return undefined;
+    throw err;
+  }
+  try {
+    const pkg = JSON.parse(raw) as Record<string, unknown>;
+    return parsePackageMetadata(pkg);
+  } catch {
+    // Malformed JSON -- treat as non-extension package.
+    return undefined;
+  }
+}
+
+/**
+ * Discover project extensions living under `extensions/` in the project root.
+ *
+ * Looks for `extensions/<name>/src/index.ts` and `extensions/<name>/index.ts`.
+ */
+export async function discoverProjectExtensions(
+  baseDir: string,
+): Promise<string[]> {
+  const extDir = join(baseDir, "extensions");
+  const entries = await readDir(extDir);
+  const results: string[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory) continue;
+    const srcIndex = join(extDir, entry.name, "src", "index.ts");
+    const rootIndex = join(extDir, entry.name, "index.ts");
+
+    if (await fileExists(srcIndex)) {
+      results.push(srcIndex);
+    } else if (await fileExists(rootIndex)) {
+      results.push(rootIndex);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Find `*.extension.ts` files in the project root.
+ */
+export async function discoverLocalExtensions(
+  baseDir: string,
+): Promise<string[]> {
+  const entries = await readDir(baseDir);
+  return entries
+    .filter((e) => !e.isDirectory && e.name.endsWith(".extension.ts"))
+    .map((e) => join(baseDir, e.name));
+}

package/src/src/extensions/errors.ts

@@ -0,0 +1,39 @@
+/**
+ * Extension system error definitions.
+ *
+ * @module extensions/errors
+ */
+
+import { defineError } from "../errors/index.js";
+
+export const MISSING_EXTENSION_ERROR = defineError({
+  slug: "missing-extension",
+  category: "RUNTIME",
+  status: 500,
+  title: "Required extension not found",
+  suggestion: "Install the missing extension package and add it to your configuration",
+});
+
+export const EXTENSION_VALIDATION_ERROR = defineError({
+  slug: "extension-validation",
+  category: "CONFIG",
+  status: 422,
+  title: "Extension validation failed",
+  suggestion: "Check that the extension exports a valid name, version, and capabilities array",
+});
+
+export const CIRCULAR_DEPENDENCY_ERROR = defineError({
+  slug: "extension-circular-dependency",
+  category: "CONFIG",
+  status: 422,
+  title: "Circular dependency detected between extensions",
+  suggestion: "Review the 'extends' fields in your extensions to break the cycle",
+});
+
+export const EXTENSION_CONFLICT_ERROR = defineError({
+  slug: "extension-conflict",
+  category: "CONFIG",
+  status: 409,
+  title: "Conflicting extensions detected",
+  suggestion: "Remove or disable one of the conflicting extensions in your configuration",
+});

package/src/src/extensions/factory-loader.ts

@@ -0,0 +1,76 @@
+/**
+ * Dynamic factory loader.
+ *
+ * Loads an extension factory from a filesystem path by dynamic import,
+ * invokes it, and wraps the result as a `ResolvedExtension`.
+ *
+ * @module extensions/factory-loader
+ */
+
+import { isAbsolute, toFileUrl } from "../../deps/jsr.io/@std/path/1.1.4/mod.js";
+import { EXTENSION_VALIDATION_ERROR } from "./errors.js";
+import type { Extension, ExtensionFactory, ExtensionSource, ResolvedExtension } from "./types.js";
+
+/**
+ * Dynamically import an extension factory from `path` and resolve it.
+ *
+ * `path` may be either an absolute filesystem path (for project and
+ * local-file sources) or a bare module specifier (for `package` source).
+ * Absolute paths are converted to `file://` URLs; bare specifiers are
+ * passed through so the runtime's module resolver can find them.
+ *
+ * The module must `export default` an `ExtensionFactory` (a function that
+ * returns an `Extension`). On any error — missing default export, default
+ * export that is not a function, factory throw, or import failure — this
+ * throws `EXTENSION_VALIDATION_ERROR` with a `detail` field that names the
+ * path and what went wrong.
+ *
+ * @param path Absolute filesystem path or bare module specifier.
+ * @param source Where the extension was discovered (drives merge priority).
+ * @param config Optional config forwarded to the factory.
+ */
+export async function loadExtensionFactory(
+  path: string,
+  source: ExtensionSource,
+  config?: unknown,
+): Promise<ResolvedExtension> {
+  const specifier = isAbsolute(path) ? toFileUrl(path).href : path;
+  let mod: { default?: unknown };
+  try {
+    mod = await import(specifier);
+  } catch (err) {
+    throw EXTENSION_VALIDATION_ERROR.create({
+      detail: `Failed to import extension at "${path}": ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+      cause: err,
+    });
+  }
+
+  const factory = mod.default;
+  if (factory === undefined || factory === null) {
+    throw EXTENSION_VALIDATION_ERROR.create({
+      detail: `Extension at "${path}" has no default export`,
+    });
+  }
+
+  if (typeof factory !== "function") {
+    throw EXTENSION_VALIDATION_ERROR.create({
+      detail: `Extension at "${path}" default export is not a function (got ${typeof factory})`,
+    });
+  }
+
+  let extension: Extension;
+  try {
+    extension = (factory as ExtensionFactory)(config);
+  } catch (err) {
+    throw EXTENSION_VALIDATION_ERROR.create({
+      detail: `Extension factory at "${path}" threw during invocation: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+      cause: err,
+    });
+  }
+
+  return { extension, source, origin: path };
+}

package/src/src/extensions/index.ts

@@ -0,0 +1,79 @@
+/**
+ * Public extension API surface.
+ *
+ * Types used when authoring extensions (the scaffold template generated by
+ * `veryfront extension init` imports from this module), plus the runtime
+ * helpers consumers need to load, validate, and orchestrate extensions.
+ *
+ * @module extensions
+ * @example
+ * ```ts
+ * import { orchestrateExtensions } from "veryfront/extensions";
+ *
+ * const loader = await orchestrateExtensions({
+ *   projectDir: Deno.cwd(),
+ *   config,
+ *   logger,
+ * });
+ *
+ * // Later, on shutdown:
+ * await loader.teardownAll();
+ * ```
+ */
+
+// Core types
+import "../../_dnt.polyfills.js";
+
+export type {
+  Capability,
+  Extension,
+  ExtensionConfigEntry,
+  ExtensionContext,
+  ExtensionFactory,
+  ExtensionLogger,
+  ExtensionSource,
+  ResolvedExtension,
+} from "./types.js";
+
+// Contract registry — resolve/tryResolve are the consumer-facing API.
+// register()/reset() are internal primitives (used by ExtensionLoader and
+// tests) and are intentionally not exported here.
+export { resolve, tryResolve } from "./contracts.js";
+
+// Discovery
+export type { PackageMetadata } from "./discovery.js";
+export {
+  discoverLocalExtensions,
+  discoverPackageExtensions,
+  discoverProjectExtensions,
+  mergeExtensions,
+  parsePackageMetadata,
+} from "./discovery.js";
+
+// Loader
+export { ExtensionLoader } from "./loader.js";
+
+// Factory loader (dynamic-import of an extension factory)
+export { loadExtensionFactory } from "./factory-loader.js";
+
+// Orchestrator (discover → load → merge → setup)
+export type { OrchestrateOptions } from "./orchestrate.js";
+export { orchestrateExtensions } from "./orchestrate.js";
+
+// Validation
+export type { ConflictInfo } from "./validation.js";
+export { detectConflicts, validateExtension } from "./validation.js";
+
+// Capabilities
+export { auditCapabilities, formatCapabilities, mapToDenoPermissions } from "./capabilities.js";
+
+// Recommendations
+export { getRecommendation } from "./recommendations.js";
+
+// Errors
+export {
+  CIRCULAR_DEPENDENCY_ERROR,
+  EXTENSION_CONFLICT_ERROR,
+  EXTENSION_VALIDATION_ERROR,
+  MISSING_EXTENSION_ERROR,
+} from "./errors.js";

package/src/src/extensions/interfaces/ai-model-provider.ts

@@ -0,0 +1,100 @@
+/**
+ * Contract interface for AI/LLM model providers.
+ *
+ * Default implementation: `@veryfront/ext-openai`
+ *
+ * @module extensions/interfaces/ai-model-provider
+ */
+
+/** A single part of a multi-modal message (text or image). */
+export interface ContentPart {
+  /** Part type. */
+  type: "text" | "image";
+  /** Text content (when `type` is `"text"`). */
+  text?: string;
+  /** Image URL or base64 data (when `type` is `"image"`). */
+  imageUrl?: string;
+}
+
+/** A chat message in a conversation. */
+export interface ChatMessage {
+  /** Message role. */
+  role: "system" | "user" | "assistant" | "tool";
+  /** Simple text content. */
+  content?: string;
+  /** Multi-modal content parts (used instead of `content`). */
+  parts?: ContentPart[];
+  /** Tool call ID this message responds to (for `tool` role). */
+  toolCallId?: string;
+}
+
+/** Definition of a tool the model may invoke. */
+export interface ToolDefinition {
+  /** Tool name. */
+  name: string;
+  /** Human-readable description of what the tool does. */
+  description: string;
+  /** JSON Schema describing the tool's parameters. */
+  parameters: Record<string, unknown>;
+}
+
+/** Options passed to {@link AIModelProvider.complete} and {@link AIModelProvider.stream}. */
+export interface CompletionOptions {
+  /** Model identifier (e.g. `"gpt-4o"`, `"claude-sonnet-4-20250514"`). */
+  model: string;
+  /** Conversation messages. */
+  messages: ChatMessage[];
+  /** Sampling temperature. */
+  temperature?: number;
+  /** Maximum tokens to generate. */
+  maxTokens?: number;
+  /** Available tools for function calling. */
+  tools?: ToolDefinition[];
+  /** Additional provider-specific options. */
+  [key: string]: unknown;
+}
+
+/** Result returned from {@link AIModelProvider.complete}. */
+export interface CompletionResult {
+  /** Generated text content. */
+  content: string;
+  /** Tool calls requested by the model, if any. */
+  toolCalls?: Array<{
+    id: string;
+    name: string;
+    arguments: string;
+  }>;
+  /** Token usage statistics. */
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+
+/** A chunk emitted during streaming completion. */
+export interface StreamChunk {
+  /** Incremental text delta. */
+  content?: string;
+  /** Incremental tool call delta. */
+  toolCallDelta?: {
+    id?: string;
+    name?: string;
+    arguments?: string;
+  };
+  /** Whether this is the final chunk. */
+  done: boolean;
+}
+
+/**
+ * AIModelProvider contract interface.
+ *
+ * Implementations provide chat completion and streaming capabilities
+ * against large language models.
+ */
+export interface AIModelProvider {
+  /** Generate a complete response for the given conversation. */
+  complete(options: CompletionOptions): Promise<CompletionResult>;
+  /** Stream a response token-by-token. */
+  stream(options: CompletionOptions): AsyncIterable<StreamChunk>;
+}

package/src/src/extensions/interfaces/auth-provider.ts

@@ -0,0 +1,52 @@
+/**
+ * Contract interface for authentication token providers.
+ *
+ * Default implementation: `@veryfront/ext-jwt`
+ *
+ * @module extensions/interfaces/auth-provider
+ */
+
+/** Payload data stored within a signed token. */
+export interface TokenPayload {
+  /** Subject identifier (typically a user ID). */
+  sub: string;
+  /** Expiration time as a Unix timestamp (seconds). */
+  exp?: number;
+  /** Issued-at time as a Unix timestamp (seconds). */
+  iat?: number;
+  /** Additional claims. */
+  [key: string]: unknown;
+}
+
+/** Options for signing a token. */
+export interface SignOptions {
+  /** Token lifetime (e.g. `"1h"`, `"7d"`, or seconds as a number). */
+  expiresIn?: string | number;
+  /** Signing algorithm (e.g. `"HS256"`, `"RS256"`). */
+  algorithm?: string;
+  /** Additional implementation-specific options. */
+  [key: string]: unknown;
+}
+
+/** Options for verifying a token. */
+export interface VerifyOptions {
+  /** Expected algorithms to accept. */
+  algorithms?: string[];
+  /** Additional implementation-specific options. */
+  [key: string]: unknown;
+}
+
+/**
+ * AuthProvider contract interface.
+ *
+ * Implementations sign, verify, and decode authentication tokens
+ * (e.g. JWTs) for request authentication.
+ */
+export interface AuthProvider {
+  /** Sign a payload into a token string. */
+  sign(payload: TokenPayload, options?: SignOptions): Promise<string>;
+  /** Verify a token and return its decoded payload. Throws on invalid tokens. */
+  verify(token: string, options?: VerifyOptions): Promise<TokenPayload>;
+  /** Decode a token without verifying its signature. */
+  decode(token: string): TokenPayload | undefined;
+}