@treeseed/sdk 0.1.2 → 0.3.1

package/dist/treeseed/template-catalog/catalog.fixture.json

@@ -0,0 +1,55 @@
+{
+  "items": [
+    {
+      "id": "starter-basic",
+      "displayName": "TreeSeed Basic",
+      "description": "Opinionated first-party TreeSeed starter for documentation-first teams.",
+      "summary": "A general-purpose starter for Astro, Cloudflare, docs, and the standard Treeseed workflow.",
+      "status": "live",
+      "featured": true,
+      "category": "starter",
+      "audience": [
+        "maintainers",
+        "teams"
+      ],
+      "tags": [
+        "starter",
+        "astro",
+        "cloudflare",
+        "docs"
+      ],
+      "publisher": {
+        "id": "treeseed",
+        "name": "TreeSeed",
+        "url": "https://treeseed.ai"
+      },
+      "publisherVerified": true,
+      "templateVersion": "1.0.0",
+      "templateApiVersion": 1,
+      "minCliVersion": "0.1.1",
+      "minCoreVersion": "0.1.2",
+      "fulfillment": {
+        "source": {
+          "kind": "git",
+          "repoUrl": "https://github.com/treeseed-ai/market.git",
+          "directory": "templates/starter-basic",
+          "ref": "main",
+          "integrity": "catalog-fixture"
+        },
+        "hooksPolicy": "builtin_only",
+        "supportsReconcile": true
+      },
+      "offer": {
+        "priceModel": "free",
+        "license": "AGPL-3.0-only",
+        "support": "community"
+      },
+      "relatedBooks": [],
+      "relatedKnowledge": [],
+      "relatedObjectives": []
+    }
+  ],
+  "meta": {
+    "source": "fixture"
+  }
+}

package/dist/treeseed/template-catalog/templates/starter-basic/template/astro.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/dist/treeseed/template-catalog/templates/starter-basic/template/astro.config.ts

@@ -0,0 +1,3 @@
+import { createTreeseedTenantSite } from '@treeseed/core/config';
+
+export default createTreeseedTenantSite();

package/dist/treeseed/template-catalog/templates/starter-basic/template/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "__SITE_SLUG__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "packageManager": "npm@11.7.0",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "setup": "npm install",
+    "setup:ci": "npm ci",
+    "config": "treeseed config",
+    "dev": "treeseed dev",
+    "dev:watch": "treeseed dev --watch",
+    "check": "treeseed check",
+    "build": "treeseed build",
+    "deploy": "treeseed deploy",
+    "preview": "treeseed preview",
+    "sync": "treeseed sync",
+    "verify": "npm run check && npm run build"
+  },
+  "dependencies": {
+    "@treeseed/cli": "__CLI_VERSION__",
+    "@treeseed/core": "__CORE_VERSION__",
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.9.3"
+  }
+}

package/dist/treeseed/template-catalog/templates/starter-basic/template/src/config.yaml

@@ -0,0 +1,40 @@
+site:
+  name: __SITE_NAME__
+  statement: A Treeseed site generated from the basic starter template.
+  siteUrl: __SITE_URL__
+  githubRepository: __REPOSITORY_URL__
+  discordLink: __DISCORD_URL__
+  headerMenu:
+    - label: Learn
+      items:
+        - label: Handbook
+          href: /knowledge/handbook/
+    - label: Build
+      items:
+        - label: Welcome
+          href: /welcome/
+  footerMenu:
+    - label: Project
+      items:
+        - label: Repository
+          href: __REPOSITORY_URL__
+  forms:
+    apiBaseUrl: /api/form/submit
+  emailNotifications:
+    contactRouting:
+      default:
+        - __CONTACT_EMAIL__
+    subscribeRecipients:
+      - __CONTACT_EMAIL__
+  summary: __SITE_NAME__ is a Treeseed site generated from the basic starter.
+  projectStage: Initial build
+  projectStageDetail: Generated from the Treeseed basic starter template.
+models:
+  pages:
+    defaults:
+      pageLayout: article
+      stage: starter
+      audience: []
+  docs:
+    defaults:
+      tags: []

package/dist/treeseed/template-catalog/templates/starter-basic/template/src/content/empty/.gitkeep

@@ -0,0 +1 @@
+

package/dist/treeseed/template-catalog/templates/starter-basic/template/src/content/knowledge/handbook/index.mdx

@@ -0,0 +1,11 @@
+---
+title: Handbook
+description: Starter handbook for the generated Treeseed site.
+tags:
+  - handbook
+  - starter
+---
+
+`__SITE_NAME__` is connected to the Treeseed runtime through `@treeseed/core`.
+
+Use this handbook as the first docs collection entry.

package/dist/treeseed/template-catalog/templates/starter-basic/template/src/content/pages/welcome.mdx

@@ -0,0 +1,11 @@
+---
+title: Welcome
+description: Welcome page for the generated Treeseed starter site.
+slug: welcome
+summary: A starter page proving the tenant content pipeline is wired correctly.
+updated: 2026-04-08
+---
+
+Welcome to `__SITE_NAME__`.
+
+This site was generated from the TreeSeed basic starter.

package/dist/treeseed/template-catalog/templates/starter-basic/template/src/content.config.d.ts

@@ -0,0 +1 @@
+export declare const collections: any;

package/dist/treeseed/template-catalog/templates/starter-basic/template/src/content.config.ts

@@ -0,0 +1,3 @@
+import { createTreeseedTenantCollections } from '@treeseed/core/content-config';
+
+export const collections = createTreeseedTenantCollections();

package/dist/treeseed/template-catalog/templates/starter-basic/template/src/env.yaml

@@ -0,0 +1 @@
+entries: {}

package/dist/treeseed/template-catalog/templates/starter-basic/template/src/manifest.yaml

@@ -0,0 +1,19 @@
+id: __SITE_SLUG__
+siteConfigPath: ./src/config.yaml
+content:
+  docs: ./src/content/knowledge
+  pages: ./src/content/pages
+  notes: ./src/content/empty
+  questions: ./src/content/empty
+  objectives: ./src/content/empty
+  people: ./src/content/empty
+  agents: ./src/content/empty
+  books: ./src/content/empty
+features:
+  docs: true
+  books: false
+  notes: false
+  questions: false
+  objectives: false
+  agents: false
+  forms: false

package/dist/treeseed/template-catalog/templates/starter-basic/template/treeseed.site.yaml

@@ -0,0 +1,26 @@
+name: __SITE_NAME__
+slug: __SITE_SLUG__
+siteUrl: __SITE_URL__
+contactEmail: __CONTACT_EMAIL__
+cloudflare:
+  accountId: replace-with-cloudflare-account-id
+  workerName: __SITE_SLUG__
+plugins:
+  - package: '@treeseed/core/plugin-default'
+providers:
+  forms: store_only
+  agents:
+    execution: stub
+    mutation: local_branch
+    repository: stub
+    verification: stub
+    notification: stub
+    research: stub
+  deploy: cloudflare
+  content:
+    docs: default
+  site: default
+smtp:
+  enabled: false
+turnstile:
+  enabled: false

package/dist/treeseed/template-catalog/templates/starter-basic/template/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@treeseed/core/tsconfigs/strict",
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "types": ["node"]
+  },
+  "include": ["src/**/*", "astro.config.ts"]
+}

package/dist/treeseed/template-catalog/templates/starter-basic/template.config.json

@@ -0,0 +1,90 @@
+{
+  "schemaVersion": 1,
+  "id": "starter-basic",
+  "displayName": "TreeSeed Basic",
+  "description": "Opinionated first-party TreeSeed starter for documentation-first teams.",
+  "category": "starter",
+  "tags": [
+    "starter",
+    "astro",
+    "cloudflare",
+    "docs"
+  ],
+  "templateVersion": "1.0.0",
+  "templateApiVersion": 1,
+  "minCliVersion": "0.1.1",
+  "minCoreVersion": "0.1.2",
+  "variables": [
+    {
+      "name": "Site name",
+      "token": "__SITE_NAME__",
+      "deriveFrom": "name",
+      "required": true
+    },
+    {
+      "name": "Site slug",
+      "token": "__SITE_SLUG__",
+      "deriveFrom": "slug",
+      "required": true
+    },
+    {
+      "name": "Site URL",
+      "token": "__SITE_URL__",
+      "deriveFrom": "siteUrl",
+      "default": "https://example.com",
+      "required": true
+    },
+    {
+      "name": "Contact email",
+      "token": "__CONTACT_EMAIL__",
+      "deriveFrom": "contactEmail",
+      "default": "hello@example.com",
+      "required": true
+    },
+    {
+      "name": "Repository URL",
+      "token": "__REPOSITORY_URL__",
+      "deriveFrom": "repositoryUrl",
+      "default": "https://github.com/example/site"
+    },
+    {
+      "name": "Discord URL",
+      "token": "__DISCORD_URL__",
+      "deriveFrom": "discordUrl",
+      "default": "https://discord.gg/example"
+    },
+    {
+      "name": "CLI version",
+      "token": "__CLI_VERSION__",
+      "deriveFrom": "cliVersion",
+      "required": true
+    },
+    {
+      "name": "Core version",
+      "token": "__CORE_VERSION__",
+      "deriveFrom": "coreVersion",
+      "required": true
+    }
+  ],
+  "managedSurface": {
+    "coreManaged": [
+      "package.json",
+      "astro.config.ts",
+      "tsconfig.json",
+      "treeseed.site.yaml",
+      "src/content.config.ts",
+      "src/config.yaml",
+      "src/manifest.yaml",
+      "src/env.yaml"
+    ],
+    "validatedOnly": [
+      "treeseed.site.yaml",
+      "src/config.yaml",
+      "src/manifest.yaml",
+      "src/env.yaml"
+    ]
+  },
+  "testing": {
+    "buildCommand": "npm run build"
+  }
+}

package/dist/utils/agents/contracts/messages.d.ts

@@ -0,0 +1,88 @@
+export interface QuestionPriorityUpdatedMessage {
+    questionId: string;
+    reason: string;
+    plannerRunId: string;
+}
+export interface ObjectivePriorityUpdatedMessage {
+    objectiveId: string;
+    reason: string;
+    plannerRunId: string;
+}
+export interface ArchitectureUpdatedMessage {
+    objectiveId: string;
+    knowledgeId: string;
+    architectRunId: string;
+}
+export interface SubscriberNotifiedMessage {
+    email: string;
+    itemCount: number;
+    notifierRunId: string;
+}
+export interface ResearchStartedMessage {
+    questionId: string;
+    researcherRunId: string;
+}
+export interface ResearchCompletedMessage {
+    questionId: string;
+    knowledgeId: string | null;
+    researcherRunId: string;
+}
+export interface TaskCompleteMessage {
+    branchName: string | null;
+    changedTargets: string[];
+    engineerRunId: string;
+}
+export interface TaskWaitingMessage {
+    blockingReason: string;
+    engineerRunId: string;
+}
+export interface TaskFailedMessage {
+    failureSummary: string;
+    engineerRunId: string;
+}
+export interface TaskVerifiedMessage {
+    branchName: string | null;
+    reviewerRunId: string;
+}
+export interface ReviewFailedMessage {
+    failureSummary: string;
+    reviewerRunId: string;
+}
+export interface ReviewWaitingMessage {
+    blockingReason: string;
+    reviewerRunId: string;
+}
+export interface ReleaseStartedMessage {
+    taskRunId: string | null;
+    releaserRunId: string;
+}
+export interface ReleaseCompletedMessage {
+    releaseSummary: string;
+    releaserRunId: string;
+}
+export interface ReleaseFailedMessage {
+    failureSummary: string;
+    releaserRunId: string;
+}
+export interface AgentMessageContracts {
+    question_priority_updated: QuestionPriorityUpdatedMessage;
+    objective_priority_updated: ObjectivePriorityUpdatedMessage;
+    architecture_updated: ArchitectureUpdatedMessage;
+    subscriber_notified: SubscriberNotifiedMessage;
+    research_started: ResearchStartedMessage;
+    research_completed: ResearchCompletedMessage;
+    task_complete: TaskCompleteMessage;
+    task_waiting: TaskWaitingMessage;
+    task_failed: TaskFailedMessage;
+    task_verified: TaskVerifiedMessage;
+    review_failed: ReviewFailedMessage;
+    review_waiting: ReviewWaitingMessage;
+    release_started: ReleaseStartedMessage;
+    release_completed: ReleaseCompletedMessage;
+    release_failed: ReleaseFailedMessage;
+}
+export type AgentMessageType = keyof AgentMessageContracts;
+export type AgentMessagePayload<TType extends AgentMessageType> = AgentMessageContracts[TType];
+export declare const AGENT_MESSAGE_TYPES: readonly ["question_priority_updated", "objective_priority_updated", "architecture_updated", "subscriber_notified", "research_started", "research_completed", "task_complete", "task_waiting", "task_failed", "task_verified", "review_failed", "review_waiting", "release_started", "release_completed", "release_failed"];
+export declare function parseAgentMessagePayload<TType extends AgentMessageType>(type: TType, payloadJson: string): AgentMessagePayload<TType>;
+export declare function serializeAgentMessagePayload<TType extends AgentMessageType>(type: TType, payload: AgentMessagePayload<TType>): string;

package/dist/utils/agents/contracts/messages.js

@@ -0,0 +1,138 @@
+const AGENT_MESSAGE_TYPES = [
+  "question_priority_updated",
+  "objective_priority_updated",
+  "architecture_updated",
+  "subscriber_notified",
+  "research_started",
+  "research_completed",
+  "task_complete",
+  "task_waiting",
+  "task_failed",
+  "task_verified",
+  "review_failed",
+  "review_waiting",
+  "release_started",
+  "release_completed",
+  "release_failed"
+];
+function ensureString(value, label) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`Invalid ${label}: expected non-empty string.`);
+  }
+  return value;
+}
+function ensureOptionalString(value, label) {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  return ensureString(value, label);
+}
+function ensureStringArray(value, label) {
+  if (!Array.isArray(value)) {
+    throw new Error(`Invalid ${label}: expected array.`);
+  }
+  return value.map((entry, index) => ensureString(entry, `${label}[${index}]`));
+}
+function ensureNumber(value, label) {
+  if (typeof value !== "number" || Number.isNaN(value)) {
+    throw new Error(`Invalid ${label}: expected number.`);
+  }
+  return value;
+}
+function parseAgentMessagePayload(type, payloadJson) {
+  const parsed = JSON.parse(payloadJson);
+  switch (type) {
+    case "question_priority_updated":
+      return {
+        questionId: ensureString(parsed.questionId, "questionId"),
+        reason: ensureString(parsed.reason, "reason"),
+        plannerRunId: ensureString(parsed.plannerRunId, "plannerRunId")
+      };
+    case "objective_priority_updated":
+      return {
+        objectiveId: ensureString(parsed.objectiveId, "objectiveId"),
+        reason: ensureString(parsed.reason, "reason"),
+        plannerRunId: ensureString(parsed.plannerRunId, "plannerRunId")
+      };
+    case "architecture_updated":
+      return {
+        objectiveId: ensureString(parsed.objectiveId, "objectiveId"),
+        knowledgeId: ensureString(parsed.knowledgeId, "knowledgeId"),
+        architectRunId: ensureString(parsed.architectRunId, "architectRunId")
+      };
+    case "subscriber_notified":
+      return {
+        email: ensureString(parsed.email, "email"),
+        itemCount: ensureNumber(parsed.itemCount, "itemCount"),
+        notifierRunId: ensureString(parsed.notifierRunId, "notifierRunId")
+      };
+    case "research_started":
+      return {
+        questionId: ensureString(parsed.questionId, "questionId"),
+        researcherRunId: ensureString(parsed.researcherRunId, "researcherRunId")
+      };
+    case "research_completed":
+      return {
+        questionId: ensureString(parsed.questionId, "questionId"),
+        knowledgeId: ensureOptionalString(parsed.knowledgeId, "knowledgeId"),
+        researcherRunId: ensureString(parsed.researcherRunId, "researcherRunId")
+      };
+    case "task_complete":
+      return {
+        branchName: ensureOptionalString(parsed.branchName, "branchName"),
+        changedTargets: ensureStringArray(parsed.changedTargets, "changedTargets"),
+        engineerRunId: ensureString(parsed.engineerRunId, "engineerRunId")
+      };
+    case "task_waiting":
+      return {
+        blockingReason: ensureString(parsed.blockingReason, "blockingReason"),
+        engineerRunId: ensureString(parsed.engineerRunId, "engineerRunId")
+      };
+    case "task_failed":
+      return {
+        failureSummary: ensureString(parsed.failureSummary, "failureSummary"),
+        engineerRunId: ensureString(parsed.engineerRunId, "engineerRunId")
+      };
+    case "task_verified":
+      return {
+        branchName: ensureOptionalString(parsed.branchName, "branchName"),
+        reviewerRunId: ensureString(parsed.reviewerRunId, "reviewerRunId")
+      };
+    case "review_failed":
+      return {
+        failureSummary: ensureString(parsed.failureSummary, "failureSummary"),
+        reviewerRunId: ensureString(parsed.reviewerRunId, "reviewerRunId")
+      };
+    case "review_waiting":
+      return {
+        blockingReason: ensureString(parsed.blockingReason, "blockingReason"),
+        reviewerRunId: ensureString(parsed.reviewerRunId, "reviewerRunId")
+      };
+    case "release_started":
+      return {
+        taskRunId: ensureOptionalString(parsed.taskRunId, "taskRunId"),
+        releaserRunId: ensureString(parsed.releaserRunId, "releaserRunId")
+      };
+    case "release_completed":
+      return {
+        releaseSummary: ensureString(parsed.releaseSummary, "releaseSummary"),
+        releaserRunId: ensureString(parsed.releaserRunId, "releaserRunId")
+      };
+    case "release_failed":
+      return {
+        failureSummary: ensureString(parsed.failureSummary, "failureSummary"),
+        releaserRunId: ensureString(parsed.releaserRunId, "releaserRunId")
+      };
+    default:
+      throw new Error(`Unknown agent message type "${String(type)}".`);
+  }
+}
+function serializeAgentMessagePayload(type, payload) {
+  parseAgentMessagePayload(type, JSON.stringify(payload));
+  return JSON.stringify(payload);
+}
+export {
+  AGENT_MESSAGE_TYPES,
+  parseAgentMessagePayload,
+  serializeAgentMessagePayload
+};

package/dist/utils/agents/contracts/run.d.ts

@@ -0,0 +1,20 @@
+export type AgentErrorCategory = 'trigger_resolution_error' | 'permission_error' | 'message_claim_error' | 'lease_error' | 'execution_error' | 'mutation_error' | 'sdk_error';
+export interface AgentRunTrace {
+    [key: string]: unknown;
+    runId: string;
+    agentSlug: string;
+    handlerKind: string;
+    triggerKind: string;
+    triggerSource: string;
+    claimedMessageId: number | null;
+    selectedItemKey: string | null;
+    branchName: string | null;
+    commitSha: string | null;
+    changedPaths: string[];
+    summary: string | null;
+    error: string | null;
+    errorCategory: AgentErrorCategory | null;
+    startedAt: string;
+    finishedAt: string | null;
+    status: string;
+}