@treeseed/sdk 0.10.28 → 0.11.0

package/dist/treedx-backends.js

@@ -0,0 +1,632 @@
+import path from "node:path";
+import { TreeDxApiError, TreeDxClient } from "./treedx-client.js";
+import { parseFrontmatterDocument, serializeFrontmatterDocument } from "./frontmatter.js";
+import { resolveModelDefinition } from "./model-registry.js";
+import { applyFilters, applySort } from "./sdk-filters.js";
+import {
+  canonicalizeFrontmatter,
+  normalizeFilterFields,
+  normalizeMutationData,
+  normalizeRecordToCanonicalShape,
+  normalizeSortFields,
+  readCanonicalFieldValue
+} from "./sdk-fields.js";
+import { assertExpectedVersion } from "./sdk-version.js";
+class TreeDxContentRepositoryConfigError extends Error {
+  constructor(message = 'TreeDX content repository is not configured. Set TREESEED_TREEDX_BASE_URL or pass treeDx.baseUrl, or select contentRepository.adapter = "local".') {
+    super(message);
+    this.name = "TreeDxContentRepositoryConfigError";
+  }
+}
+function compactObject(input) {
+  return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== void 0));
+}
+function stringValue(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function arrayFromPayload(value) {
+  if (Array.isArray(value)) return value;
+  if (value && typeof value === "object") {
+    const record = value;
+    for (const key of ["items", "repositories", "repos", "data"]) {
+      if (Array.isArray(record[key])) return record[key];
+    }
+  }
+  return [];
+}
+function repoIdFromRepository(repository) {
+  return stringValue(repository.id) ?? stringValue(repository.repoId) ?? stringValue(repository.repo_id) ?? stringValue(repository.name) ?? stringValue(repository.slug);
+}
+function repositoryMatchesHint(repository, hint) {
+  const name = stringValue(repository.name) ?? stringValue(repository.slug);
+  const owner = stringValue(repository.owner) ?? stringValue(repository.metadata?.owner);
+  const remoteUrl = stringValue(repository.remoteUrl) ?? stringValue(repository.remote_url) ?? stringValue(repository.cloneUrl) ?? stringValue(repository.clone_url) ?? stringValue(repository.url);
+  const defaultBranch = stringValue(repository.defaultBranch) ?? stringValue(repository.default_branch) ?? stringValue(repository.branch);
+  const metadata = repository.metadata && typeof repository.metadata === "object" ? repository.metadata : {};
+  if (hint.purpose && metadata.purpose !== hint.purpose && repository.purpose !== hint.purpose) return false;
+  if (hint.name && name !== hint.name) return false;
+  if (hint.owner && owner !== hint.owner) return false;
+  if (hint.remoteUrl && remoteUrl !== hint.remoteUrl) return false;
+  if (hint.defaultBranch && defaultBranch !== hint.defaultBranch) return false;
+  return true;
+}
+function normalizePathPattern(pattern) {
+  return pattern.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function segment(value) {
+  return encodeURIComponent(value);
+}
+function isMarkdownPath(value) {
+  return /\.(md|mdx)$/i.test(value);
+}
+function inferSlug(filePath, pathPattern) {
+  const normalizedPath = normalizePathPattern(filePath);
+  const root = normalizePathPattern(pathPattern).replace(/\*\*.*$/u, "").replace(/\/?$/u, "/");
+  const withoutRoot = normalizedPath.startsWith(root) ? normalizedPath.slice(root.length) : normalizedPath;
+  return withoutRoot.replace(/\.(md|mdx)$/i, "");
+}
+function normalizePathList(value) {
+  if (Array.isArray(value)) {
+    return value.flatMap((entry) => {
+      if (typeof entry === "string") return [entry];
+      if (entry && typeof entry === "object") {
+        const record = entry;
+        const candidate = stringValue(record.path) ?? stringValue(record.file) ?? stringValue(record.key);
+        return candidate ? [candidate] : [];
+      }
+      return [];
+    });
+  }
+  if (value && typeof value === "object") {
+    const record = value;
+    for (const key of ["paths", "items", "files", "results", "data"]) {
+      const normalized = normalizePathList(record[key]);
+      if (normalized.length > 0) return normalized;
+    }
+  }
+  return [];
+}
+function extractTextPayload(value) {
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object") {
+    const record = value;
+    for (const key of ["content", "body", "text", "source", "data"]) {
+      const candidate = record[key];
+      if (typeof candidate === "string") return candidate;
+      if (candidate && typeof candidate === "object") {
+        const nested = extractTextPayload(candidate);
+        if (nested) return nested;
+      }
+    }
+  }
+  return "";
+}
+function normalizeFilesPayload(value) {
+  if (Array.isArray(value)) {
+    return value.filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry)));
+  }
+  if (value && typeof value === "object") {
+    const record = value;
+    for (const key of ["results", "files", "items", "data"]) {
+      const normalized = normalizeFilesPayload(record[key]);
+      if (normalized.length > 0) return normalized;
+    }
+  }
+  return [];
+}
+function entryFromTreeDxPayload(definition, file, contentRoot) {
+  const filePath = stringValue(file.path) ?? stringValue(file.file) ?? stringValue(file.key) ?? "";
+  const parsed = file.frontmatter && typeof file.frontmatter === "object" ? {
+    frontmatter: file.frontmatter,
+    body: typeof file.body === "string" ? file.body : extractTextPayload(file)
+  } : parseFrontmatterDocument(extractTextPayload(file));
+  const slug = inferSlug(filePath, contentRoot);
+  return {
+    id: slug,
+    slug,
+    model: definition.name,
+    title: titleForEntry(definition, parsed.frontmatter),
+    path: filePath,
+    body: parsed.body,
+    frontmatter: parsed.frontmatter,
+    createdAt: dateForEntry(definition, parsed.frontmatter, "created_at"),
+    updatedAt: dateForEntry(definition, parsed.frontmatter, "updated_at")
+  };
+}
+function entryMatchesIdentity(entry, request) {
+  return [request.id, request.slug, request.key].filter(Boolean).includes(entry.id) || [request.id, request.slug, request.key].filter(Boolean).includes(entry.slug);
+}
+function sanitizeFrontmatterInput(data) {
+  const next = { ...data };
+  delete next.body;
+  delete next.branchPrefix;
+  return next;
+}
+function ensureMutationAllowed(definition, operation) {
+  if (!definition.operations.includes(operation)) {
+    throw new Error(`Model "${definition.name}" does not allow ${operation}.`);
+  }
+}
+function titleForEntry(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" ? String(titleField) : typeof nameField === "string" ? String(nameField) : void 0;
+}
+function dateForEntry(definition, frontmatter, field) {
+  const value = definition.fields[field] ? readCanonicalFieldValue(definition, { frontmatter }, field) : void 0;
+  return typeof value === "string" ? String(value) : null;
+}
+function relativeContentDir(repoRoot, definition) {
+  if (!definition.contentDir) return void 0;
+  return normalizePathPattern(path.relative(repoRoot, definition.contentDir));
+}
+function makeDefaultPathRule(repoRoot, definition) {
+  const relative = relativeContentDir(repoRoot, definition) ?? `src/content/${definition.contentCollection ?? definition.name}`;
+  return { paths: [`${relative.replace(/\/$/u, "")}/**`] };
+}
+function normalizePathRule(input, fallback) {
+  if (!input) return fallback;
+  if (typeof input === "string") return { paths: [input] };
+  return input;
+}
+function mutationPath(definition, repoRoot, slug) {
+  const relative = relativeContentDir(repoRoot, definition) ?? `src/content/${definition.contentCollection ?? definition.name}`;
+  const extension = definition.name === "knowledge" ? ".md" : ".mdx";
+  return `${relative.replace(/\/$/u, "")}/${slug}${extension}`;
+}
+function resolveTreeDxOptions(input) {
+  const baseUrl = stringValue(input?.baseUrl) ?? stringValue(process.env.TREESEED_TREEDX_BASE_URL);
+  if (!baseUrl) return null;
+  return {
+    baseUrl,
+    token: stringValue(input?.token) ?? stringValue(process.env.TREESEED_TREEDX_TOKEN),
+    repoId: stringValue(input?.repoId),
+    ref: stringValue(input?.ref) ?? stringValue(process.env.TREESEED_TREEDX_REF),
+    workspaceId: stringValue(input?.workspaceId) ?? stringValue(process.env.TREESEED_TREEDX_WORKSPACE_ID),
+    contentPathMap: input?.contentPathMap,
+    repositoryHints: input?.repositoryHints ?? [],
+    fetchImpl: input?.fetchImpl
+  };
+}
+function createTreeDxClientFromAgentOptions(options) {
+  const config = compactObject({
+    baseUrl: options.baseUrl,
+    token: options.token,
+    fetchImpl: options.fetchImpl
+  });
+  return new TreeDxClient(config);
+}
+class TreeDxPortfolioResolver {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  repositoryCache = null;
+  candidateCache = /* @__PURE__ */ new Map();
+  async listRepositories() {
+    this.repositoryCache ??= this.options.client.repositories.list().then(
+      (response) => arrayFromPayload(response).filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry)))
+    );
+    return this.repositoryCache;
+  }
+  async resolveCandidates(rule) {
+    if (this.options.repoId) {
+      return rule.paths.map((path2) => ({
+        repoId: this.options.repoId,
+        ref: this.options.ref,
+        path: path2,
+        repository: { repoId: this.options.repoId }
+      }));
+    }
+    const cacheKey = JSON.stringify({
+      paths: rule.paths,
+      hints: [...this.options.repositoryHints ?? [], ...rule.repositoryHints ?? []],
+      ref: this.options.ref
+    });
+    const cached = this.candidateCache.get(cacheKey);
+    if (cached) return cached;
+    const promise = this.resolveCandidatesUncached(rule);
+    this.candidateCache.set(cacheKey, promise);
+    return promise;
+  }
+  async resolveCandidatesUncached(rule) {
+    const repositories = await this.listRepositories();
+    const hints = [...this.options.repositoryHints ?? [], ...rule.repositoryHints ?? []].filter((hint) => hint.purpose !== "site_code" && hint.purpose !== "optional_project");
+    const matching = hints.length > 0 ? repositories.filter((repository) => hints.some((hint) => repositoryMatchesHint(repository, hint))) : repositories.filter((repository) => {
+      const metadata = repository.metadata && typeof repository.metadata === "object" ? repository.metadata : {};
+      return repository.purpose !== "site_code" && repository.purpose !== "optional_project" && metadata.purpose !== "site_code" && metadata.purpose !== "optional_project";
+    });
+    return matching.flatMap((repository) => {
+      const repoId = repoIdFromRepository(repository);
+      if (!repoId) return [];
+      return rule.paths.map((rulePath) => ({
+        repoId,
+        ref: this.options.ref,
+        path: normalizePathPattern(rulePath),
+        repository
+      }));
+    });
+  }
+}
+class LocalContentBackend {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  list(model) {
+    return this.store.list(model);
+  }
+  get(request) {
+    return this.store.get(request);
+  }
+  search(request) {
+    return this.store.search(request);
+  }
+  follow(request) {
+    return this.store.follow(request);
+  }
+  pick(request) {
+    return this.store.pick(request);
+  }
+  create(request) {
+    return this.store.create(request);
+  }
+  update(request) {
+    return this.store.update(request);
+  }
+}
+class MissingTreeDxContentBackend {
+  fail() {
+    throw new TreeDxContentRepositoryConfigError();
+  }
+  list() {
+    this.fail();
+  }
+  get() {
+    this.fail();
+  }
+  search() {
+    this.fail();
+  }
+  follow() {
+    this.fail();
+  }
+  pick() {
+    this.fail();
+  }
+  create() {
+    this.fail();
+  }
+  update() {
+    this.fail();
+  }
+}
+class TreeDxContentBackend {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  definition(model) {
+    const definition = resolveModelDefinition(model, this.options.models);
+    if (definition.storage !== "content") {
+      throw new Error(`Model "${model}" is not content-backed.`);
+    }
+    return definition;
+  }
+  pathRule(definition) {
+    const configured = this.options.contentPathMap?.[definition.name];
+    return normalizePathRule(configured, makeDefaultPathRule(this.options.repoRoot, definition));
+  }
+  async readEntry(definition, candidate, filePath) {
+    const payload = await this.options.client.query.readFile(candidate.repoId, compactObject({
+      ref: candidate.ref,
+      path: filePath
+    }));
+    const parsed = parseFrontmatterDocument(extractTextPayload(payload));
+    const payloadRecord = payload && typeof payload === "object" ? payload : {};
+    const payloadFile = payloadRecord.file && typeof payloadRecord.file === "object" ? payloadRecord.file : {};
+    const resolvedPath = stringValue(payloadFile.path) ?? stringValue(payloadRecord.path) ?? filePath;
+    const slug = inferSlug(resolvedPath, candidate.path);
+    return {
+      id: slug,
+      slug,
+      model: definition.name,
+      title: titleForEntry(definition, parsed.frontmatter),
+      path: resolvedPath,
+      body: parsed.body,
+      frontmatter: parsed.frontmatter,
+      createdAt: dateForEntry(definition, parsed.frontmatter, "created_at"),
+      updatedAt: dateForEntry(definition, parsed.frontmatter, "updated_at")
+    };
+  }
+  async list(model) {
+    const definition = this.definition(model);
+    const rule = this.pathRule(definition);
+    const candidates = await this.options.resolver.resolveCandidates(rule);
+    const entries = (await Promise.all(candidates.map(async (candidate) => {
+      const listPayload = await this.options.client.query.listPaths(candidate.repoId, compactObject({
+        ref: candidate.ref,
+        path: candidate.path
+      }));
+      const paths = normalizePathList(listPayload).filter(isMarkdownPath);
+      return await Promise.all(paths.map((filePath) => this.readEntry(definition, candidate, filePath)));
+    }))).flat();
+    const deduped = /* @__PURE__ */ new Map();
+    for (const entry of entries) {
+      const existing = deduped.get(entry.id);
+      if (!existing || new Date(entry.updatedAt ?? 0).valueOf() >= new Date(existing.updatedAt ?? 0).valueOf()) {
+        deduped.set(entry.id, entry);
+      }
+    }
+    return [...deduped.values()];
+  }
+  async get(request) {
+    if (this.options.directRepoId) {
+      const definition = this.definition(request.model);
+      const rule = this.pathRule(definition);
+      const identities = [request.id, request.slug, request.key].filter((value) => Boolean(value));
+      for (const identity of identities) {
+        for (const basePath of rule.paths) {
+          for (const extension of [".md", ".mdx"]) {
+            try {
+              return await this.readEntry(definition, {
+                repoId: this.options.directRepoId,
+                ref: this.options.ref,
+                path: basePath,
+                repository: { repoId: this.options.directRepoId }
+              }, `${basePath.replace(/\/$/u, "")}/${identity}${extension}`);
+            } catch {
+            }
+          }
+        }
+      }
+      return null;
+    }
+    const entries = await this.list(request.model);
+    return entries.find((entry) => entryMatchesIdentity(entry, request)) ?? null;
+  }
+  async search(request) {
+    const definition = this.definition(request.model);
+    if (this.options.directRepoId) {
+      const rule = this.pathRule(definition);
+      const payload = await this.options.client.query.searchFiles(this.options.directRepoId, compactObject({
+        ref: this.options.ref,
+        paths: rule.paths.map((path2) => `${path2.replace(/\/$/u, "")}/**`),
+        query: "",
+        limit: request.limit,
+        includeBody: true,
+        includeFrontmatter: true
+      }));
+      const results = normalizeFilesPayload(payload);
+      return results.map((file) => entryFromTreeDxPayload(definition, file, rule.paths[0] ?? ""));
+    }
+    const items = await this.list(definition.name);
+    const filtered = applyFilters(items, normalizeFilterFields(definition, request.filters), definition);
+    const sorted = applySort(filtered, normalizeSortFields(definition, request.sort), definition);
+    return sorted.slice(0, request.limit ?? sorted.length);
+  }
+  async follow(request) {
+    const items = await this.search({
+      model: request.model,
+      filters: [
+        ...request.filters ?? [],
+        { field: "updatedAt", op: "updated_since", value: request.since }
+      ]
+    });
+    return { items, since: request.since };
+  }
+  pick(request) {
+    return this.options.localLeaseStore.pick(request);
+  }
+  async resolveWritePath(definition, slug) {
+    if (this.options.workspaceId) return mutationPath(definition, this.options.repoRoot, slug);
+    const candidates = await this.options.resolver.resolveCandidates(this.pathRule(definition));
+    const repositoryIds = new Set(candidates.map((candidate) => candidate.repoId));
+    if (repositoryIds.size === 0) {
+      throw new Error(`No TreeDX repository candidate found for ${definition.name} content.`);
+    }
+    if (repositoryIds.size > 1) {
+      throw new Error(`Ambiguous TreeDX repository candidates for ${definition.name} content. Configure repositoryHints or provide a workspaceId.`);
+    }
+    return mutationPath(definition, this.options.repoRoot, slug);
+  }
+  requireWorkspaceId() {
+    if (!this.options.workspaceId) {
+      throw new Error("TreeDX content writes require treeDx.workspaceId in Phase 9.");
+    }
+    return this.options.workspaceId;
+  }
+  async createDirectWorkspace() {
+    if (!this.options.directRepoId) return null;
+    const response = await this.options.client.transport.request({
+      method: "POST",
+      path: `/api/v1/repos/${segment(this.options.directRepoId)}/workspaces`,
+      body: { mode: "writable" }
+    });
+    const payload = response.data;
+    return stringValue(payload.workspaceId) ?? stringValue(payload.id) ?? null;
+  }
+  async commitDirectWorkspace(workspaceId, filePath) {
+    await this.options.client.transport.request({
+      method: "POST",
+      path: `/api/v1/workspaces/${segment(workspaceId)}/commit`,
+      body: {
+        message: `Update ${filePath}`,
+        paths: [filePath]
+      }
+    });
+  }
+  async create(request) {
+    const definition = this.definition(request.model);
+    ensureMutationAllowed(definition, "create");
+    const slug = String(request.data.slug ?? request.data.id ?? cryptoRandomId());
+    const body = typeof request.data.body === "string" ? request.data.body : "";
+    const mutationData = normalizeMutationData(definition, sanitizeFrontmatterInput(request.data));
+    const frontmatter = canonicalizeFrontmatter(definition, {}, {
+      ...mutationData,
+      slug,
+      updated_at: mutationData.updated_at ?? (/* @__PURE__ */ new Date()).toISOString()
+    });
+    const filePath = await this.resolveWritePath(definition, slug);
+    const workspaceId = this.options.workspaceId ?? await this.createDirectWorkspace() ?? this.requireWorkspaceId();
+    await this.options.client.files.write(workspaceId, {
+      path: filePath,
+      content: serializeFrontmatterDocument(frontmatter, body)
+    });
+    if (!this.options.workspaceId && this.options.directRepoId) {
+      await this.commitDirectWorkspace(workspaceId, filePath);
+      return {
+        item: await this.readEntry(definition, {
+          repoId: this.options.directRepoId,
+          ref: this.options.ref,
+          path: this.pathRule(definition).paths[0] ?? "",
+          repository: { repoId: this.options.directRepoId }
+        }, filePath),
+        git: null
+      };
+    }
+    return {
+      item: {
+        id: slug,
+        slug,
+        model: definition.name,
+        title: titleForEntry(definition, frontmatter),
+        path: filePath,
+        body,
+        frontmatter,
+        createdAt: dateForEntry(definition, frontmatter, "created_at"),
+        updatedAt: dateForEntry(definition, frontmatter, "updated_at")
+      },
+      git: null
+    };
+  }
+  async update(request) {
+    const definition = this.definition(request.model);
+    ensureMutationAllowed(definition, "update");
+    const workspaceId = this.requireWorkspaceId();
+    const existing = await this.get(request);
+    if (!existing) {
+      throw new Error(`No ${request.model} entry found for update.`);
+    }
+    assertExpectedVersion(request.expectedVersion, existing, `${definition.name} "${existing.slug}"`);
+    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;
+    await this.options.client.files.patch(workspaceId, {
+      path: existing.path,
+      content: serializeFrontmatterDocument(nextFrontmatter, nextBody)
+    });
+    return {
+      item: {
+        ...existing,
+        title: titleForEntry(definition, nextFrontmatter),
+        body: nextBody,
+        frontmatter: nextFrontmatter,
+        updatedAt: dateForEntry(definition, nextFrontmatter, "updated_at")
+      },
+      git: null
+    };
+  }
+}
+function cryptoRandomId() {
+  return globalThis.crypto?.randomUUID?.() ?? `treedx-${Date.now()}`;
+}
+class LocalGraphBackend {
+  constructor(runtime) {
+    this.runtime = runtime;
+  }
+  runtime;
+  refresh(request) {
+    return this.runtime.refresh(request);
+  }
+  queryGraph(request) {
+    return this.runtime.queryGraph(request);
+  }
+  buildContextPack(request) {
+    return this.runtime.buildContextPack(request);
+  }
+  parseGraphDsl(source) {
+    return this.runtime.parseGraphDsl(source);
+  }
+}
+class TreeDxGraphBackend {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  async refresh(request) {
+    const candidates = await this.options.resolver.resolveCandidates({
+      paths: request?.paths?.length ? request.paths : ["**"]
+    });
+    return Promise.all(candidates.map(
+      (candidate) => this.options.client.graph.refresh(candidate.repoId, compactObject({
+        ref: candidate.ref ?? this.options.ref,
+        paths: request?.paths
+      }))
+    ));
+  }
+  async repoIds() {
+    const repositories = await this.options.resolver.listRepositories();
+    return repositories.flatMap((repository) => {
+      const repoId = repoIdFromRepository(repository);
+      return repoId ? [repoId] : [];
+    });
+  }
+  async queryGraph(request) {
+    return this.options.client.federation.graphQuery({
+      ...request,
+      repoIds: await this.repoIds(),
+      ref: this.options.ref
+    });
+  }
+  async buildContextPack(request) {
+    return this.options.client.federation.contextBuild({
+      ...request,
+      repoIds: await this.repoIds(),
+      ref: this.options.ref
+    });
+  }
+  parseGraphDsl(source) {
+    return this.options.localRuntime.parseGraphDsl(source);
+  }
+}
+class LocalExecBackend {
+  async run(input) {
+    return input;
+  }
+}
+class TreeDxExecBackend {
+  constructor(client, workspaceId) {
+    this.client = client;
+    this.workspaceId = workspaceId;
+  }
+  client;
+  workspaceId;
+  run(input) {
+    if (!this.workspaceId) {
+      throw new Error("TreeDX exec requires treeDx.workspaceId.");
+    }
+    return this.client.exec.run(this.workspaceId, input);
+  }
+}
+export {
+  LocalContentBackend,
+  LocalExecBackend,
+  LocalGraphBackend,
+  MissingTreeDxContentBackend,
+  TreeDxApiError,
+  TreeDxContentBackend,
+  TreeDxContentRepositoryConfigError,
+  TreeDxExecBackend,
+  TreeDxGraphBackend,
+  TreeDxPortfolioResolver,
+  createTreeDxClientFromAgentOptions,
+  resolveTreeDxOptions
+};