@treeseed/sdk 0.10.28 → 0.12.4

package/dist/treedx/repository-adapter.js

@@ -0,0 +1,319 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { resolveModelDefinition } from "../model-registry.js";
+import { parseFrontmatterDocument, serializeFrontmatterDocument } from "../frontmatter.js";
+import {
+  canonicalizeFrontmatter,
+  normalizeFilterFields,
+  normalizeMutationData,
+  normalizeRecordToCanonicalShape,
+  normalizeSortFields,
+  readCanonicalFieldValue
+} from "../sdk-fields.js";
+import { TreeDxApiError } from "./errors.js";
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeRepoPath(value) {
+  return value.replace(/\\/g, "/").replace(/^\/+/u, "").replace(/\/+$/u, "");
+}
+function stripExtension(value) {
+  return value.replace(/\.(md|mdx)$/iu, "");
+}
+function sanitizeFrontmatterInput(data) {
+  const next = { ...data };
+  delete next.body;
+  delete next.branchPrefix;
+  return next;
+}
+function ensureContentModel(definition) {
+  if (definition.storage !== "content" || !definition.contentDir) {
+    throw new TreeDxApiError(`Model "${definition.name}" is not content-backed.`, {
+      status: 400,
+      code: "model_not_content_backed"
+    });
+  }
+}
+function ensureMutationAllowed(definition, operation) {
+  if (!definition.operations.includes(operation)) {
+    throw new TreeDxApiError(`Model "${definition.name}" does not allow ${operation}.`, {
+      status: 403,
+      code: "operation_not_allowed"
+    });
+  }
+}
+function resolveContentDir(definition, options) {
+  ensureContentModel(definition);
+  const mapped = options.contentPathMap?.[definition.name];
+  if (mapped) {
+    return normalizeRepoPath(mapped);
+  }
+  const contentDir = definition.contentDir;
+  if (!path.isAbsolute(contentDir)) {
+    return normalizeRepoPath(contentDir);
+  }
+  if (options.repoRoot) {
+    return normalizeRepoPath(path.relative(options.repoRoot, contentDir));
+  }
+  const marker = `${path.sep}src${path.sep}content${path.sep}`;
+  const index = contentDir.lastIndexOf(marker);
+  if (index >= 0) {
+    return normalizeRepoPath(path.join("src", "content", contentDir.slice(index + marker.length)));
+  }
+  throw new TreeDxApiError(`Model "${definition.name}" needs a TreeDX content path mapping.`, {
+    status: 400,
+    code: "missing_content_path_mapping"
+  });
+}
+function treeDxField(field) {
+  if (["path", "name", "extension", "body", "content", "title"].includes(field)) {
+    return field;
+  }
+  return `frontmatter.${field}`;
+}
+function mapFilters(definition, filters = []) {
+  return normalizeFilterFields(definition, filters).map((filter) => ({
+    ...filter,
+    field: treeDxField(filter.field)
+  }));
+}
+function mapSort(definition, sort = []) {
+  return normalizeSortFields(definition, sort).map((entry) => ({
+    ...entry,
+    field: treeDxField(entry.field)
+  }));
+}
+function titleFrom(definition, frontmatter) {
+  const titleField = definition.fields.title ? readCanonicalFieldValue(definition, { frontmatter }, "title") : void 0;
+  const nameField = definition.fields.name ? readCanonicalFieldValue(definition, { frontmatter }, "name") : void 0;
+  return typeof titleField === "string" ? titleField : typeof nameField === "string" ? nameField : void 0;
+}
+function textFromTreeDxFile(file, keys) {
+  for (const key of keys) {
+    const value = file[key];
+    if (typeof value === "string" && value.trim()) return value;
+  }
+  return null;
+}
+function entryFromTreeDxFile(definition, value, contentDir) {
+  const file = isRecord(value) && isRecord(value.file) ? value.file : value;
+  if (!isRecord(file)) {
+    throw new TreeDxApiError("TreeDX file response was not an object.", {
+      status: 500,
+      code: "invalid_response",
+      payload: value
+    });
+  }
+  const filePath = String(file.path ?? "");
+  const rawDocument = textFromTreeDxFile(file, ["content", "source", "text"]);
+  const parsed = rawDocument ? parseFrontmatterDocument(rawDocument) : {
+    frontmatter: isRecord(file.frontmatter) ? file.frontmatter : {},
+    body: textFromTreeDxFile(file, ["body"]) ?? ""
+  };
+  const { frontmatter, body } = parsed;
+  const slug = stripExtension(normalizeRepoPath(path.posix.relative(contentDir, filePath)));
+  const created = frontmatter.created_at ?? frontmatter.createdAt ?? null;
+  const updated = frontmatter.updated_at ?? frontmatter.updatedAt ?? null;
+  return {
+    id: slug,
+    slug,
+    model: definition.name,
+    title: titleFrom(definition, frontmatter),
+    path: filePath,
+    body,
+    frontmatter,
+    createdAt: typeof created === "string" ? created : null,
+    updatedAt: typeof updated === "string" ? updated : null
+  };
+}
+function pickSortForStrategy(definition, request) {
+  switch (request.strategy) {
+    case "oldest":
+      return [{ field: definition.pickField, direction: "asc" }];
+    case "highest_priority":
+      if (definition.sortableFields.includes("priority") || definition.filterableFields.includes("priority")) {
+        return [
+          { field: "priority", direction: "desc" },
+          { field: definition.pickField, direction: "desc" }
+        ];
+      }
+      return [{ field: definition.pickField, direction: "desc" }];
+    case "latest":
+    default:
+      return [{ field: definition.pickField, direction: "desc" }];
+  }
+}
+class TreeDxRepositoryAdapter {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  async list(model) {
+    const definition = resolveModelDefinition(model, this.options.models);
+    const contentDir = resolveContentDir(definition, this.options);
+    const paths = await this.options.client.listRepositoryPaths({
+      ref: this.options.defaultRef,
+      paths: [`${contentDir}/**`],
+      extensions: [".md", ".mdx"],
+      limit: 500
+    });
+    const filePaths = (paths.entries ?? []).filter(isRecord).map((entry) => String(entry.path ?? "")).filter(Boolean);
+    if (filePaths.length === 0) {
+      return [];
+    }
+    const files = await this.options.client.readRepositoryFiles({
+      ref: this.options.defaultRef,
+      paths: filePaths,
+      parseFrontmatter: true
+    });
+    return (files.files ?? []).map((file) => entryFromTreeDxFile(definition, file, contentDir));
+  }
+  async get(request) {
+    const definition = resolveModelDefinition(request.model, this.options.models);
+    const contentDir = resolveContentDir(definition, this.options);
+    const candidates = [request.id, request.slug, request.key].filter((value) => Boolean(value));
+    for (const candidate of candidates) {
+      for (const extension of [".mdx", ".md"]) {
+        try {
+          const response = await this.options.client.readRepositoryFile({
+            ref: this.options.defaultRef,
+            path: `${contentDir}/${candidate}${extension}`,
+            parseFrontmatter: true
+          });
+          if (response.file) {
+            return entryFromTreeDxFile(definition, response.file, contentDir);
+          }
+        } catch (error) {
+          if (!(error instanceof TreeDxApiError) || error.status !== 404) {
+            throw error;
+          }
+        }
+      }
+    }
+    return null;
+  }
+  async search(request) {
+    const definition = resolveModelDefinition(request.model, this.options.models);
+    const contentDir = resolveContentDir(definition, this.options);
+    const response = await this.options.client.searchRepositoryFiles({
+      ref: this.options.defaultRef,
+      paths: [`${contentDir}/**`],
+      query: "",
+      filters: mapFilters(definition, request.filters),
+      sort: mapSort(definition, request.sort),
+      limit: request.limit,
+      includeBody: true,
+      includeFrontmatter: true
+    });
+    const results = response.results ?? response.files ?? [];
+    return results.map((file) => entryFromTreeDxFile(definition, file, contentDir));
+  }
+  async follow(request) {
+    const items = await this.search({
+      model: request.model,
+      filters: [
+        ...request.filters ?? [],
+        { field: "updated_at", op: "updated_since", value: request.since }
+      ]
+    });
+    return { items, since: request.since };
+  }
+  async pick(request) {
+    throw new TreeDxApiError("TreeDX remote content leases are not implemented by the TreeDX remote graph adapter.", {
+      status: 501,
+      code: "not_implemented",
+      details: { strategy: request.strategy ?? "latest", sort: pickSortForStrategy(resolveModelDefinition(request.model, this.options.models), request) }
+    });
+  }
+  async create(request) {
+    const definition = resolveModelDefinition(request.model, this.options.models);
+    ensureMutationAllowed(definition, "create");
+    const contentDir = resolveContentDir(definition, this.options);
+    const slug = String(request.data.slug ?? request.data.id ?? crypto.randomUUID());
+    const extension = definition.name === "knowledge" ? ".md" : ".mdx";
+    const filePath = `${contentDir}/${slug}${extension}`;
+    const mutationData = normalizeMutationData(definition, sanitizeFrontmatterInput(request.data));
+    const body = typeof request.data.body === "string" ? request.data.body : "";
+    const frontmatter = canonicalizeFrontmatter(definition, {}, {
+      ...mutationData,
+      slug,
+      updated_at: mutationData.updated_at ?? (/* @__PURE__ */ new Date()).toISOString()
+    });
+    return this.writeAndCommit(definition, contentDir, filePath, serializeFrontmatterDocument(frontmatter, body), {
+      branchName: `refs/heads/${String(request.data.branchPrefix ?? this.options.branchPrefix ?? "agent")}/${definition.name}-${slug}`,
+      message: `agent(${definition.name}): create ${slug}`
+    });
+  }
+  async update(request) {
+    const definition = resolveModelDefinition(request.model, this.options.models);
+    ensureMutationAllowed(definition, "update");
+    const contentDir = resolveContentDir(definition, this.options);
+    const existing = await this.get(request);
+    if (!existing) {
+      throw new TreeDxApiError(`No ${request.model} entry found for update.`, {
+        status: 404,
+        code: "not_found"
+      });
+    }
+    const mutationData = normalizeMutationData(definition, sanitizeFrontmatterInput(request.data));
+    const nextFrontmatter = canonicalizeFrontmatter(
+      definition,
+      normalizeRecordToCanonicalShape(definition, existing.frontmatter),
+      {
+        ...mutationData,
+        updated_at: mutationData.updated_at ?? (/* @__PURE__ */ new Date()).toISOString()
+      }
+    );
+    const nextBody = typeof request.data.body === "string" ? request.data.body : existing.body;
+    return this.writeAndCommit(definition, contentDir, existing.path, serializeFrontmatterDocument(nextFrontmatter, nextBody), {
+      branchName: `refs/heads/${String(request.data.branchPrefix ?? this.options.branchPrefix ?? "agent")}/${definition.name}-${existing.slug}`,
+      message: `agent(${definition.name}): update ${existing.slug}`,
+      expectedSha: request.expectedVersion
+    });
+  }
+  async writeAndCommit(definition, contentDir, filePath, content, options) {
+    const workspace = await this.options.client.createWorkspace({
+      baseRef: this.options.defaultRef ?? "refs/heads/main",
+      branchName: options.branchName,
+      mode: "writable",
+      allowedPaths: [`${contentDir}/**`]
+    });
+    try {
+      await this.options.client.writeFile({
+        workspaceId: workspace.workspaceId,
+        path: filePath,
+        encoding: "utf8",
+        content,
+        expectedSha: options.expectedSha
+      });
+      const git = await this.options.client.commit({
+        workspaceId: workspace.workspaceId,
+        message: options.message,
+        author: this.options.defaultAuthor ?? {
+          name: "TreeDX SDK",
+          email: "sdk@example.invalid"
+        }
+      });
+      const response = await this.options.client.readRepositoryFile({
+        ref: git.branchName,
+        path: filePath,
+        parseFrontmatter: true
+      });
+      return {
+        item: entryFromTreeDxFile(definition, response.file, contentDir),
+        git
+      };
+    } catch (error) {
+      await this.options.client.closeWorkspace(workspace.workspaceId).catch(() => {
+      });
+      throw error;
+    }
+  }
+}
+export {
+  TreeDxRepositoryAdapter,
+  entryFromTreeDxFile,
+  mapFilters,
+  mapSort,
+  resolveContentDir
+};

package/dist/treedx/sdk-integration.d.ts

@@ -0,0 +1,27 @@
+import { TreeDxClient, type TreeDxClientOptions } from './client.js';
+import { TreeDxFederatedClient } from './federated-client.js';
+import { TreeDxRegistryClient, type TreeDxRegistryClientOptions } from './registry-client.js';
+export interface AgentSdkTreeDxOptions {
+    enabled: boolean;
+    client?: TreeDxClient | TreeDxClientOptions;
+    baseUrl?: string;
+    token?: string;
+    repoId?: string;
+    contentPathMap?: Record<string, string>;
+    registryRouting?: boolean;
+    registryClient?: TreeDxRegistryClient | TreeDxRegistryClientOptions;
+    federatedClient?: TreeDxFederatedClient;
+    defaultRef?: string;
+    defaultAuthor?: {
+        name: string;
+        email: string;
+    };
+    branchPrefix?: string;
+}
+export interface AgentSdkTreeDxIntegration {
+    client: TreeDxClient;
+    repoId: string;
+    registry?: TreeDxRegistryClient;
+    federated?: TreeDxFederatedClient;
+}
+export declare function resolveAgentTreeDxIntegration(options: AgentSdkTreeDxOptions): AgentSdkTreeDxIntegration;

package/dist/treedx/sdk-integration.js

@@ -0,0 +1,63 @@
+import { TreeDxClient } from "./client.js";
+import { TreeDxFederatedClient } from "./federated-client.js";
+import { TreeDxRegistryClient } from "./registry-client.js";
+function optionsRepoId(options) {
+  if (options.repoId) {
+    return options.repoId;
+  }
+  if (options.client && !(options.client instanceof TreeDxClient)) {
+    return options.client.repoId;
+  }
+  return void 0;
+}
+function optionsToken(options) {
+  if (options.token) {
+    return options.token;
+  }
+  if (options.client && !(options.client instanceof TreeDxClient)) {
+    return options.client.token;
+  }
+  return void 0;
+}
+function optionsFetch(options) {
+  if (options.client && !(options.client instanceof TreeDxClient)) {
+    return options.client.fetch;
+  }
+  return void 0;
+}
+function buildClient(options) {
+  if (options.client instanceof TreeDxClient) {
+    return options.client;
+  }
+  if (options.client) {
+    return new TreeDxClient(options.client);
+  }
+  if (!options.baseUrl) {
+    throw new Error("AgentSdk TreeDX mode requires a client or baseUrl.");
+  }
+  return new TreeDxClient({
+    baseUrl: options.baseUrl,
+    token: options.token,
+    repoId: options.repoId
+  });
+}
+function resolveAgentTreeDxIntegration(options) {
+  const client = buildClient(options);
+  const repoId = optionsRepoId(options);
+  if (!repoId) {
+    throw new Error("AgentSdk TreeDX mode requires a repoId.");
+  }
+  if (!options.registryRouting && !options.registryClient && !options.federatedClient) {
+    return { client, repoId };
+  }
+  const registry = options.registryClient instanceof TreeDxRegistryClient ? options.registryClient : new TreeDxRegistryClient(options.registryClient ?? client);
+  const federated = options.federatedClient ?? new TreeDxFederatedClient({
+    registry,
+    token: optionsToken(options),
+    fetch: optionsFetch(options)
+  });
+  return { client, repoId, registry, federated };
+}
+export {
+  resolveAgentTreeDxIntegration
+};