@treeseed/sdk 0.10.27 → 0.11.0

package/dist/treedx/ports.js

@@ -0,0 +1,231 @@
+class LocalRepositoryPort {
+  constructor(content) {
+    this.content = content;
+  }
+  content;
+  list(model) {
+    return this.content.list(model);
+  }
+  get(input) {
+    return this.content.get(input);
+  }
+  search(input) {
+    return this.content.search(input);
+  }
+  follow(input) {
+    return this.content.follow(input);
+  }
+  pick(input) {
+    return this.content.pick(input);
+  }
+  create(input) {
+    return this.content.create(input);
+  }
+  update(input) {
+    return this.content.update(input);
+  }
+}
+class LocalRepositoryQueryPort {
+  constructor(content) {
+    this.content = content;
+  }
+  content;
+  search(input) {
+    return this.content.search(input);
+  }
+  query(input) {
+    return this.content.search(input);
+  }
+}
+class LocalGraphPort {
+  constructor(runtime) {
+    this.runtime = runtime;
+  }
+  runtime;
+  refresh(input) {
+    return this.runtime.refresh(input);
+  }
+  searchFiles(query, options) {
+    return this.runtime.searchFiles(query, options);
+  }
+  searchSections(query, options) {
+    return this.runtime.searchSections(query, options);
+  }
+  searchEntities(query, options) {
+    return this.runtime.searchEntities(query, options);
+  }
+  getNode(id) {
+    return this.runtime.getNode(id);
+  }
+  query(input) {
+    return this.runtime.queryGraph(input);
+  }
+  buildContext(input) {
+    return this.runtime.buildContextPack(input);
+  }
+  parseDsl(source) {
+    return this.runtime.parseGraphDsl(source);
+  }
+}
+class TreeDxRepositoryPort {
+  constructor(client, content, workspace) {
+    this.client = client;
+    this.content = content;
+    this.workspace = workspace;
+  }
+  client;
+  content;
+  workspace;
+  createWorkspace(input) {
+    return this.client.createWorkspace(input);
+  }
+  closeWorkspace(workspaceId) {
+    return this.client.closeWorkspace(workspaceId);
+  }
+  listTree(input) {
+    return this.client.listTree(input);
+  }
+  readFile(input) {
+    return this.client.readFile(input);
+  }
+  writeFile(input) {
+    return this.client.writeFile(input);
+  }
+  patchFile(input) {
+    return this.client.patchFile(input);
+  }
+  deleteFile(input) {
+    return this.client.deleteFile(input);
+  }
+  search(input) {
+    return this.client.search(input);
+  }
+  status(input) {
+    return this.client.status(input);
+  }
+  diff(input) {
+    return this.client.diff(input);
+  }
+  commit(input) {
+    return this.client.commit(input);
+  }
+  exec(input) {
+    return this.client.exec(input);
+  }
+}
+class TreeDxRepositoryQueryPort {
+  constructor(client, adapter) {
+    this.client = client;
+    this.adapter = adapter;
+  }
+  client;
+  adapter;
+  read(input) {
+    return this.client.readRepositoryFiles(input);
+  }
+  paths(input) {
+    return this.client.listRepositoryPaths(input);
+  }
+  query(input) {
+    return this.adapter?.queryRepository(input) ?? this.client.queryRepository(input);
+  }
+  search(input) {
+    return this.client.searchRepositoryFiles(input);
+  }
+}
+class TreeDxGraphPort {
+  constructor(adapter) {
+    this.adapter = adapter;
+  }
+  adapter;
+  refresh(input) {
+    return this.adapter.refresh(input);
+  }
+  searchFiles(query, options) {
+    return this.adapter.searchFiles(query, options);
+  }
+  searchSections(query, options) {
+    return this.adapter.searchSections(query, options);
+  }
+  searchEntities(query, options) {
+    return this.adapter.searchEntities(query, options);
+  }
+  getNode(id, options) {
+    return this.adapter.getNode(id, options);
+  }
+  query(input) {
+    return this.adapter.queryGraph(input);
+  }
+  buildContext(input) {
+    return this.adapter.buildContextPack(input);
+  }
+  parseDsl(source) {
+    return this.adapter.parseGraphDsl(source);
+  }
+}
+class TreeDxRegistryPort {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  resolveRepository(repoId) {
+    return this.client.resolveRepository(repoId);
+  }
+  resolveRepositories(repoIds) {
+    return this.client.resolveRepositories(repoIds);
+  }
+}
+class TreeDxFederatedPort {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  search(input) {
+    return this.client.federatedSearch(input);
+  }
+  query(input) {
+    return this.client.federatedQuery(input);
+  }
+  context(input) {
+    return this.client.federatedContext(input);
+  }
+  graph(input) {
+    return this.client.federatedGraph(input);
+  }
+}
+class TreeDxExecPort {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  exec(input) {
+    return this.client.exec(input);
+  }
+}
+class TreeDxArtifactPort {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  buildSnapshot(input = {}) {
+    return this.client.buildSnapshot(input);
+  }
+  exportArtifact(input = {}) {
+    return this.client.exportArtifact(input);
+  }
+  downloadArtifact(input = {}) {
+    return this.client.downloadArtifact(input);
+  }
+}
+export {
+  LocalGraphPort,
+  LocalRepositoryPort,
+  LocalRepositoryQueryPort,
+  TreeDxArtifactPort,
+  TreeDxExecPort,
+  TreeDxFederatedPort,
+  TreeDxGraphPort,
+  TreeDxRegistryPort,
+  TreeDxRepositoryPort,
+  TreeDxRepositoryQueryPort
+};

package/dist/treedx/query-adapter.d.ts

@@ -0,0 +1,19 @@
+import type { SdkContentEntry, SdkGetRequest, SdkModelRegistry, SdkSearchRequest } from '../sdk-types.ts';
+import { TreeDxClient } from './client.ts';
+import type { TreeDxRepositoryQueryRequest, TreeDxRepositoryQueryResult } from './types.ts';
+export interface TreeDxQueryAdapterOptions {
+    client: TreeDxClient;
+    models: SdkModelRegistry;
+    repoRoot?: string;
+    contentPathMap?: Record<string, string>;
+    defaultRef?: string;
+}
+export declare class TreeDxQueryAdapter {
+    private readonly options;
+    constructor(options: TreeDxQueryAdapterOptions);
+    readContent(request: SdkGetRequest): Promise<SdkContentEntry | null>;
+    search(request: SdkSearchRequest): Promise<SdkContentEntry[]>;
+    searchContent(request: SdkSearchRequest): Promise<SdkContentEntry[]>;
+    query(input: TreeDxRepositoryQueryRequest): Promise<TreeDxRepositoryQueryResult>;
+    queryRepository(input: TreeDxRepositoryQueryRequest): Promise<TreeDxRepositoryQueryResult>;
+}

package/dist/treedx/query-adapter.js

@@ -0,0 +1,62 @@
+import {
+  entryFromTreeDxFile,
+  mapFilters,
+  mapSort,
+  resolveContentDir
+} from "./repository-adapter.js";
+import { resolveModelDefinition } from "../model-registry.js";
+class TreeDxQueryAdapter {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  async readContent(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 {
+        }
+      }
+    }
+    return null;
+  }
+  async search(request) {
+    return this.searchContent(request);
+  }
+  async searchContent(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));
+  }
+  query(input) {
+    return this.options.client.queryRepository(input);
+  }
+  queryRepository(input) {
+    return this.query(input);
+  }
+}
+export {
+  TreeDxQueryAdapter
+};

package/dist/treedx/registry-client.d.ts

@@ -0,0 +1,11 @@
+import { TreeDxClient } from './client.ts';
+import type { TreeDxClientOptions, TreeDxNode, TreeDxRepositoryPlacement } from './types.ts';
+export interface TreeDxRegistryClientOptions extends TreeDxClientOptions {
+}
+export declare class TreeDxRegistryClient {
+    readonly client: TreeDxClient;
+    constructor(options: TreeDxRegistryClientOptions | TreeDxClient);
+    listNodes(): Promise<TreeDxNode[]>;
+    resolveRepository(repoId: string): Promise<TreeDxRepositoryPlacement>;
+    resolveRepositories(repoIds: string[]): Promise<TreeDxRepositoryPlacement[]>;
+}

package/dist/treedx/registry-client.js

@@ -0,0 +1,19 @@
+import { TreeDxClient } from "./client.js";
+class TreeDxRegistryClient {
+  client;
+  constructor(options) {
+    this.client = options instanceof TreeDxClient ? options : new TreeDxClient(options);
+  }
+  listNodes() {
+    return this.client.listNodes();
+  }
+  resolveRepository(repoId) {
+    return this.client.getPlacement(repoId);
+  }
+  resolveRepositories(repoIds) {
+    return Promise.all(repoIds.map((repoId) => this.resolveRepository(repoId)));
+  }
+}
+export {
+  TreeDxRegistryClient
+};

package/dist/treedx/repository-adapter.d.ts

@@ -0,0 +1,45 @@
+import type { SdkContentEntry, SdkFilterCondition, SdkFollowRequest, SdkGetRequest, SdkModelDefinition, SdkModelRegistry, SdkMutationRequest, SdkPickRequest, SdkPickResult, SdkSearchRequest, SdkSortSpec, SdkUpdateRequest } from '../sdk-types.ts';
+import { TreeDxClient } from './client.ts';
+import type { TreeDxCommitResult } from './types.ts';
+export interface TreeDxRepositoryAdapterOptions {
+    client: TreeDxClient;
+    models: SdkModelRegistry;
+    repoRoot?: string;
+    defaultRef?: string;
+    defaultAuthor?: {
+        name: string;
+        email: string;
+    };
+    contentPathMap?: Record<string, string>;
+    branchPrefix?: string;
+}
+export interface TreeDxContentMutationResult {
+    item: SdkContentEntry;
+    git: TreeDxCommitResult;
+}
+export declare function resolveContentDir(definition: SdkModelDefinition, options: Pick<TreeDxRepositoryAdapterOptions, 'contentPathMap' | 'repoRoot'>): string;
+export declare function mapFilters(definition: SdkModelDefinition, filters?: SdkFilterCondition[]): {
+    field: string;
+    op: import("../sdk-types.ts").SdkFilterOperator;
+    value: unknown;
+}[];
+export declare function mapSort(definition: SdkModelDefinition, sort?: SdkSortSpec[]): {
+    field: string;
+    direction?: "asc" | "desc";
+}[];
+export declare function entryFromTreeDxFile(definition: SdkModelDefinition, value: unknown, contentDir: string): SdkContentEntry;
+export declare class TreeDxRepositoryAdapter {
+    private readonly options;
+    constructor(options: TreeDxRepositoryAdapterOptions);
+    list(model: string): Promise<SdkContentEntry[]>;
+    get(request: SdkGetRequest): Promise<SdkContentEntry | null>;
+    search(request: SdkSearchRequest): Promise<SdkContentEntry[]>;
+    follow(request: SdkFollowRequest): Promise<{
+        items: SdkContentEntry[];
+        since: string;
+    }>;
+    pick(request: SdkPickRequest): Promise<SdkPickResult<SdkContentEntry>>;
+    create(request: SdkMutationRequest): Promise<TreeDxContentMutationResult>;
+    update(request: SdkUpdateRequest): Promise<TreeDxContentMutationResult>;
+    private writeAndCommit;
+}

package/dist/treedx/repository-adapter.js

@@ -0,0 +1,308 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { resolveModelDefinition } from "../model-registry.js";
+import { 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 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 frontmatter = isRecord(file.frontmatter) ? file.frontmatter : {};
+  const body = typeof file.body === "string" ? file.body : typeof file.content === "string" ? file.content : "";
+  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
+};