@treeseed/sdk 0.4.0 → 0.4.1

package/README.md

@@ -102,6 +102,19 @@ ctx <target>
 
 The old `key=value` graph DSL is no longer supported.
 
+## Shared Fixture Support
+
+SDK also owns the shared fixture support model used across the Treeseed workspace.
+
+That support layer is responsible for:
+
+- resolving the canonical shared fixture in `.fixtures/treeseed-fixtures`
+- preparing fixture-local package visibility for package-scoped verification
+- linking real workspace or installed packages into the fixture runtime when available
+- providing the canonical `contracts-only` Agent shim used by packages such as `core` during isolated verification
+
+The shared fixture is an integrated Treeseed project, but package verification remains package-scoped. SDK owns the tooling that lets other packages validate their own slice of that project without mutating the fixture itself.
+
 ## Advanced Graph Methods
 
 The SDK also exposes lower-level graph primitives such as:
@@ -166,3 +179,9 @@ npm install
 npm run build
 npm test
 ```
+
+For fixture-specific work:
+
+```bash
+npm run fixtures:check
+```

package/dist/fixture-support.d.ts

@@ -0,0 +1,24 @@
+export type FixtureInjectionMode = 'workspace-link' | 'installed-link' | 'contracts-only';
+export type FixtureSupportDeclaration = {
+    packageName: string;
+    modes: readonly FixtureInjectionMode[];
+    workspaceDirName?: string;
+    entrySpecifier?: string;
+    contractsShim?: 'agent';
+};
+export type ResolveSharedFixtureOptions = {
+    packageRoot?: string;
+    requiredPaths?: string[];
+};
+export type PrepareFixturePackagesOptions = {
+    fixtureRoot: string;
+    packageRoot?: string;
+    declarations: readonly FixtureSupportDeclaration[];
+};
+export declare const DEFAULT_FIXTURE_ID = "treeseed-working-site";
+export declare function resolveRequestedFixtureId(): string;
+export declare function resolveFixturesRepoRoot(options?: ResolveSharedFixtureOptions): string;
+export declare function resolveSharedFixtureRoot(options?: ResolveSharedFixtureOptions): string | null;
+export declare function requireSharedFixtureRoot(options?: ResolveSharedFixtureOptions): string;
+export declare function checkSharedFixture(options?: ResolveSharedFixtureOptions): string;
+export declare function prepareFixturePackages(options: PrepareFixturePackagesOptions): void;

package/dist/fixture-support.js

@@ -0,0 +1,337 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const require2 = createRequire(import.meta.url);
+const sdkPackageRoot = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const DEFAULT_FIXTURE_ID = "treeseed-working-site";
+function currentPackageRoot(packageRoot) {
+  return packageRoot ? resolve(packageRoot) : sdkPackageRoot;
+}
+function requiredFixturePaths(requiredPaths) {
+  return requiredPaths && requiredPaths.length > 0 ? requiredPaths : ["src/manifest.yaml", "src/content"];
+}
+function resolveRequestedFixtureId() {
+  return process.env.TREESEED_FIXTURE_ID?.trim() || DEFAULT_FIXTURE_ID;
+}
+function resolveFixturesRepoRoot(options = {}) {
+  if (process.env.TREESEED_FIXTURES_ROOT?.trim()) {
+    return resolve(process.env.TREESEED_FIXTURES_ROOT);
+  }
+  return resolve(currentPackageRoot(options.packageRoot), ".fixtures", "treeseed-fixtures");
+}
+function fixtureSatisfiesRequiredPaths(root, requiredPaths) {
+  return requiredFixturePaths(requiredPaths).every((relativePath) => existsSync(join(root, relativePath)));
+}
+function resolveSharedFixtureRoot(options = {}) {
+  const fixturesRepoRoot = resolveFixturesRepoRoot(options);
+  const sitesRoot = join(fixturesRepoRoot, "sites");
+  if (!existsSync(sitesRoot)) {
+    return null;
+  }
+  const requestedFixtureId = resolveRequestedFixtureId();
+  for (const entry of readdirSync(sitesRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const fixtureRoot = join(sitesRoot, entry.name);
+    const manifestPath = join(fixtureRoot, "fixture.manifest.json");
+    if (!existsSync(manifestPath)) {
+      continue;
+    }
+    try {
+      const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+      if (manifest.id !== requestedFixtureId) {
+        continue;
+      }
+      const root = resolve(fixtureRoot, manifest.root ?? ".");
+      if (fixtureSatisfiesRequiredPaths(root, options.requiredPaths)) {
+        return root;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+function requireSharedFixtureRoot(options = {}) {
+  const fixtureRoot = resolveSharedFixtureRoot(options);
+  if (!fixtureRoot) {
+    throw new Error(
+      `Unable to resolve shared fixture "${resolveRequestedFixtureId()}". Initialize the submodule with "git submodule update --init --recursive".`
+    );
+  }
+  return fixtureRoot;
+}
+function checkSharedFixture(options = {}) {
+  const fixtureRoot = requireSharedFixtureRoot(options);
+  const missing = requiredFixturePaths(options.requiredPaths).filter((relativePath) => !existsSync(join(fixtureRoot, relativePath)));
+  if (missing.length > 0) {
+    throw new Error(`Shared fixture is missing required paths at ${fixtureRoot}: ${missing.join(", ")}.`);
+  }
+  return fixtureRoot;
+}
+function resolveInstalledPackageRoot(packageName, entrySpecifier) {
+  const candidates = [
+    `${packageName}/package.json`,
+    entrySpecifier ?? packageName,
+    packageName
+  ];
+  for (const candidate of candidates) {
+    try {
+      const resolvedEntry = require2.resolve(candidate);
+      let currentDir = dirname(resolvedEntry);
+      while (currentDir !== dirname(currentDir)) {
+        if (existsSync(resolve(currentDir, "package.json"))) {
+          return currentDir;
+        }
+        currentDir = dirname(currentDir);
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+function resolveWorkspacePackageRoot(packageRoot, workspaceDirName) {
+  if (!workspaceDirName) {
+    return null;
+  }
+  const candidate = resolve(packageRoot, "..", workspaceDirName);
+  return existsSync(resolve(candidate, "package.json")) ? candidate : null;
+}
+function ensureFixtureLinkedPackage(fixtureRoot, packageName, resolvedPackageRoot) {
+  const packageDir = resolve(fixtureRoot, "node_modules", ...packageName.split("/"));
+  mkdirSync(dirname(packageDir), { recursive: true });
+  rmSync(packageDir, { recursive: true, force: true });
+  symlinkSync(resolvedPackageRoot, packageDir, "dir");
+}
+function buildAgentContractsShimPackage(fixtureRoot) {
+  const packageDir = resolve(fixtureRoot, "node_modules", "@treeseed", "agent");
+  rmSync(packageDir, { recursive: true, force: true });
+  mkdirSync(resolve(packageDir, "contracts"), { recursive: true });
+  writeFileSync(
+    resolve(packageDir, "package.json"),
+    JSON.stringify(
+      {
+        name: "@treeseed/agent",
+        type: "module",
+        exports: {
+          "./runtime-types": {
+            types: "./runtime-types.d.js",
+            default: "./runtime-types.js"
+          },
+          "./contracts/messages": {
+            types: "./contracts/messages.d.js",
+            default: "./contracts/messages.js"
+          },
+          "./contracts/run": {
+            types: "./contracts/run.d.js",
+            default: "./contracts/run.js"
+          }
+        }
+      },
+      null,
+      2
+    ),
+    "utf8"
+  );
+  writeFileSync(resolve(packageDir, "runtime-types.js"), "export {};\n", "utf8");
+  writeFileSync(
+    resolve(packageDir, "runtime-types.d.ts"),
+    [
+      "import type { AgentHandlerKind, AgentRunStatus } from '@treeseed/sdk/types/agents';",
+      "export interface AgentTriggerInvocation {",
+      "	kind: 'startup' | 'schedule' | 'message' | 'manual' | 'follow';",
+      "	source: string;",
+      "	message?: { id?: string | number; type?: string; payloadJson?: string | null } | null;",
+      "}",
+      "export interface AgentExecutionResult {",
+      "	status: AgentRunStatus;",
+      "	summary: string;",
+      "	stdout?: string;",
+      "	stderr?: string;",
+      "	errorCategory?: import('./contracts/run').AgentErrorCategory | null;",
+      "	metadata?: Record<string, unknown>;",
+      "}",
+      "export interface AgentContext {",
+      "	runId: string;",
+      "	repoRoot: string;",
+      "	agent: any;",
+      "	sdk: any;",
+      "	trigger: AgentTriggerInvocation;",
+      "	execution: any;",
+      "	mutations: any;",
+      "	repository: any;",
+      "	verification: any;",
+      "	notifications: any;",
+      "	research: any;",
+      "}",
+      "export interface AgentHandler<TInputs = unknown, TResult = unknown> {",
+      "	kind: AgentHandlerKind;",
+      "	resolveInputs(context: AgentContext): Promise<TInputs>;",
+      "	execute(context: AgentContext, inputs: TInputs): Promise<TResult>;",
+      "	emitOutputs(context: AgentContext, result: TResult): Promise<AgentExecutionResult>;",
+      "}",
+      ""
+    ].join("\n"),
+    "utf8"
+  );
+  writeFileSync(
+    resolve(packageDir, "contracts", "messages.js"),
+    [
+      "export const AGENT_MESSAGE_TYPES = [];",
+      "export function parseAgentMessagePayload(_type, payloadJson) {",
+      "	return JSON.parse(payloadJson);",
+      "}",
+      ""
+    ].join("\n"),
+    "utf8"
+  );
+  writeFileSync(
+    resolve(packageDir, "contracts", "messages.d.ts"),
+    [
+      "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 AgentMessageType[];",
+      "export declare function parseAgentMessagePayload<TType extends AgentMessageType>(_type: TType, payloadJson: string): AgentMessagePayload<TType>;",
+      ""
+    ].join("\n"),
+    "utf8"
+  );
+  writeFileSync(resolve(packageDir, "contracts", "run.js"), "export {};\n", "utf8");
+  writeFileSync(
+    resolve(packageDir, "contracts", "run.d.ts"),
+    [
+      "export type AgentErrorCategory = 'execution_error' | 'mutation_error' | 'verification_error' | 'notification_error' | 'research_error' | 'sdk_error' | 'unknown';",
+      ""
+    ].join("\n"),
+    "utf8"
+  );
+}
+function prepareFixturePackages(options) {
+  const packageRoot = currentPackageRoot(options.packageRoot);
+  for (const declaration of options.declarations) {
+    let satisfied = false;
+    for (const mode of declaration.modes) {
+      if (mode === "workspace-link") {
+        const workspaceRoot = resolveWorkspacePackageRoot(packageRoot, declaration.workspaceDirName);
+        if (!workspaceRoot) {
+          continue;
+        }
+        ensureFixtureLinkedPackage(options.fixtureRoot, declaration.packageName, workspaceRoot);
+        satisfied = true;
+        break;
+      }
+      if (mode === "installed-link") {
+        const installedRoot = resolveInstalledPackageRoot(declaration.packageName, declaration.entrySpecifier);
+        if (!installedRoot) {
+          continue;
+        }
+        ensureFixtureLinkedPackage(options.fixtureRoot, declaration.packageName, installedRoot);
+        satisfied = true;
+        break;
+      }
+      if (mode === "contracts-only" && declaration.contractsShim === "agent") {
+        buildAgentContractsShimPackage(options.fixtureRoot);
+        satisfied = true;
+        break;
+      }
+    }
+    if (!satisfied) {
+      throw new Error(`Unable to prepare fixture package "${declaration.packageName}" using modes ${declaration.modes.join(", ")}.`);
+    }
+  }
+}
+export {
+  DEFAULT_FIXTURE_ID,
+  checkSharedFixture,
+  prepareFixturePackages,
+  requireSharedFixtureRoot,
+  resolveFixturesRepoRoot,
+  resolveRequestedFixtureId,
+  resolveSharedFixtureRoot
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@treeseed/sdk",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Shared Treeseed SDK for content-backed and D1-backed object models.",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -87,6 +87,10 @@
       "types": "./dist/verification.d.ts",
       "default": "./dist/verification.js"
     },
+    "./fixture-support": {
+      "types": "./dist/fixture-support.d.ts",
+      "default": "./dist/fixture-support.js"
+    },
     "./scripts/verify-driver": "./scripts/verify-driver.mjs",
     "./workflow-support": {
       "types": "./dist/workflow-support.d.ts",