@treeseed/sdk 0.13.0-rc.60 → 0.13.0-rc.62

package/dist/platform/schemas.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+const repositorySchema = z.object({
+  key: z.string().min(1),
+  project: z.string().min(1),
+  role: z.enum(["primary", "library", "fixture"]),
+  gitUrl: z.string().min(1),
+  defaultBranch: z.string().min(1).default("main"),
+  repositoryPolicy: z.object({ stagingBranch: z.string().min(1).optional() }).passthrough().optional()
+}).passthrough();
+const projectSchema = z.object({
+  key: z.string().min(1),
+  slug: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/u),
+  primaryRepository: z.string().min(1)
+}).passthrough();
+const inventorySchema = z.object({
+  schemaVersion: z.string().min(1),
+  resources: z.object({
+    projects: z.array(projectSchema),
+    repositories: z.array(repositorySchema)
+  }).passthrough()
+}).passthrough();
+const profileSchema = z.object({
+  schemaVersion: z.literal("treeseed.platform-profile/v1"),
+  id: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/u),
+  extends: z.array(z.string()).default([]),
+  sources: z.object({ projects: z.array(z.string()).default([]) }).default({ projects: [] }),
+  runtime: z.object({ targets: z.array(z.string()).default([]) }).passthrough().default({ targets: [] })
+}).passthrough();
+const worksetSelectionSchema = z.object({
+  profiles: z.array(z.string()).default([]),
+  projects: z.array(z.string()).default([]),
+  exclude: z.array(z.string()).default([])
+});
+const worksetEntrySchema = z.object({
+  project: z.string(),
+  repository: z.string(),
+  gitUrl: z.string(),
+  branch: z.string(),
+  commit: z.string().regex(/^[0-9a-f]{40}$/u),
+  path: z.string(),
+  action: z.enum(["clone", "fast-forward", "noop", "blocked"]),
+  blockers: z.array(z.string()).default([])
+});
+const worksetPlanSchema = z.object({
+  schemaVersion: z.literal("treeseed.platform-workset-plan/v1"),
+  root: z.string(),
+  inventoryPath: z.string(),
+  inventoryDigest: z.string(),
+  selection: worksetSelectionSchema,
+  entries: z.array(worksetEntrySchema),
+  ok: z.boolean()
+});
+const worksetReceiptSchema = z.object({
+  schemaVersion: z.literal("treeseed.platform-workset-receipt/v1"),
+  planDigest: z.string(),
+  inventoryDigest: z.string(),
+  entries: z.array(worksetEntrySchema.omit({ action: true, blockers: true }).extend({ action: z.enum(["clone", "fast-forward", "noop"]) }))
+});
+export {
+  inventorySchema,
+  profileSchema,
+  projectSchema,
+  repositorySchema,
+  worksetEntrySchema,
+  worksetPlanSchema,
+  worksetReceiptSchema,
+  worksetSelectionSchema
+};

package/dist/platform/verification.d.ts

@@ -0,0 +1,9 @@
+import type { PlatformDiagnostic } from './schemas.js';
+export interface PlatformVerification {
+    schemaVersion: 'treeseed.platform-verification/v1';
+    root: string;
+    digest: string;
+    ok: boolean;
+    diagnostics: PlatformDiagnostic[];
+}
+export declare function verifyPlatformRepository(root?: string): PlatformVerification;

package/dist/platform/verification.js

@@ -0,0 +1,104 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { extname, relative, resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+import { parse } from "yaml";
+import { hostTemplateSchema, integrationLockSchema } from "./contracts.js";
+import { inventorySchema, profileSchema } from "./schemas.js";
+const allowedRoots = /* @__PURE__ */ new Set([".github", "config", "docs", "profiles", "seeds", "templates"]);
+const allowedFiles = /* @__PURE__ */ new Set([".gitignore", "AGENTS.md", "LICENSE", "LICENSE.md", "README.md", "skills-lock.json", "treeseed.site.yaml"]);
+const allowedExtensions = /* @__PURE__ */ new Set([".md", ".yaml", ".yml", ".json", ".lock", ".toml"]);
+const forbiddenExtensions = /* @__PURE__ */ new Set([".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".py", ".sh", ".go", ".rs", ".java"]);
+const personalPath = /(?:^|[\s'"`:=])(?:\/home\/[^/\s]+|\/Users\/[^/\s]+|[A-Za-z]:\\Users\\[^\\\s]+)/u;
+function semanticDiagnostics(root, tracked) {
+  const diagnostics = [];
+  const document = (path) => parse(readFileSync(resolve(root, path), "utf8"));
+  const report = (code, path, message) => diagnostics.push({ code, path, message });
+  const safe = (path, load) => {
+    try {
+      return load();
+    } catch (error) {
+      report("declaration_invalid", path, error instanceof Error ? error.message : String(error));
+      return void 0;
+    }
+  };
+  const profiles = /* @__PURE__ */ new Map();
+  for (const path of [...tracked].filter((value) => /^profiles\/[^/]+\.ya?ml$/u.test(value))) {
+    const profile = safe(path, () => profileSchema.parse(document(path)));
+    if (profile) profiles.set(profile.id, profile);
+  }
+  const sitePath = "treeseed.site.yaml";
+  if (!tracked.has(sitePath)) return diagnostics;
+  const site = safe(sitePath, () => document(sitePath));
+  if (!site) return diagnostics;
+  const development = site.development;
+  const inventoryPath = development?.local?.inventory?.path;
+  let projectSlugs = /* @__PURE__ */ new Set();
+  if (development?.local?.inventory?.source !== "seed" || !inventoryPath || !tracked.has(inventoryPath)) {
+    report("inventory_reference_invalid", sitePath, "The local inventory must reference a tracked seed declaration.");
+  } else {
+    const inventory = safe(inventoryPath, () => inventorySchema.parse(document(inventoryPath)));
+    if (inventory) projectSlugs = new Set(inventory.resources.projects.map((project) => project.slug));
+  }
+  for (const [id, profile] of profiles) {
+    for (const project of profile.sources.projects) if (!projectSlugs.has(project)) report("profile_project_unknown", `profiles/${id}.yaml`, `Profile project ${project} is absent from the portable inventory.`);
+    for (const parent of profile.extends) if (!profiles.has(parent)) report("profile_parent_unknown", `profiles/${id}.yaml`, `Profile parent ${parent} does not exist.`);
+  }
+  const integrations = site.integrations;
+  const integrationDigests = /* @__PURE__ */ new Map();
+  for (const path of Object.values(integrations ?? {}).filter((value) => value.includes("/integrations/"))) {
+    if (!tracked.has(path)) {
+      report("integration_reference_invalid", sitePath, `Integration lock ${path} is not tracked.`);
+      continue;
+    }
+    const lock = safe(path, () => integrationLockSchema.parse(document(path)));
+    if (!lock) continue;
+    const digest = `sha256:${createHash("sha256").update(JSON.stringify(lock.components)).digest("hex")}`;
+    if (digest !== lock.digest) report("integration_digest_mismatch", path, "Integration lock digest does not bind its exact component list.");
+    integrationDigests.set(lock.release.replace(/-\d+$/u, ""), lock.digest);
+  }
+  for (const path of [...tracked].filter((value) => /^config\/hosts\/[^/]+\.ya?ml$/u.test(value))) {
+    const host = safe(path, () => hostTemplateSchema.parse(document(path)));
+    if (!host) continue;
+    for (const profile of host.profiles) if (!profiles.has(profile)) report("host_profile_unknown", path, `Host template profile ${profile} does not exist.`);
+    if (![...integrationDigests.values()].includes(host.integration.digest)) report("host_integration_unknown", path, "Host template integration digest is not present in a referenced integration lock.");
+  }
+  const production = site.production;
+  if (production?.mutation !== "blocked") report("production_not_fail_closed", sitePath, "Production mutation must remain blocked until promotion gates pass.");
+  if (production?.topology && !tracked.has(production.topology)) report("topology_reference_invalid", sitePath, "Production topology must reference a tracked declaration.");
+  return diagnostics;
+}
+function verifyPlatformRepository(root = process.cwd()) {
+  const absoluteRoot = resolve(root);
+  const listed = execFileSync("git", ["ls-files", "-z"], { cwd: absoluteRoot, encoding: "utf8" }).split("\0").filter(Boolean).sort();
+  const diagnostics = [];
+  const hash = createHash("sha256");
+  for (const path of listed) {
+    const fullPath = resolve(absoluteRoot, path);
+    if (!fullPath.startsWith(`${absoluteRoot}/`)) {
+      diagnostics.push({ code: "path_not_portable", path, message: "Tracked paths must stay beneath the repository and cannot be symbolic links." });
+      continue;
+    }
+    if (!existsSync(fullPath)) {
+      diagnostics.push({ code: "tracked_file_missing", path, message: "Tracked Platform files must exist in the working tree." });
+      continue;
+    }
+    if (lstatSync(fullPath).isSymbolicLink()) {
+      diagnostics.push({ code: "path_not_portable", path, message: "Tracked paths must stay beneath the repository and cannot be symbolic links." });
+      continue;
+    }
+    const rootSegment = path.split("/")[0];
+    const extension = extname(path);
+    if (!allowedFiles.has(path) && !allowedRoots.has(rootSegment)) diagnostics.push({ code: "content_root_forbidden", path, message: "Platform may contain only declarations, documentation, locks, and GitHub configuration." });
+    if (forbiddenExtensions.has(extension)) diagnostics.push({ code: "implementation_forbidden", path, message: "Executable implementation belongs in its owning package." });
+    if (!allowedFiles.has(path) && !allowedExtensions.has(extension)) diagnostics.push({ code: "file_type_forbidden", path, message: "This tracked file type is outside the declarative Platform boundary." });
+    const source = readFileSync(fullPath);
+    hash.update(relative(absoluteRoot, fullPath)).update("\0").update(source);
+    if (personalPath.test(source.toString("utf8"))) diagnostics.push({ code: "personal_path_forbidden", path, message: "Committed home-directory paths are forbidden." });
+  }
+  diagnostics.push(...semanticDiagnostics(absoluteRoot, new Set(listed)));
+  return { schemaVersion: "treeseed.platform-verification/v1", root: absoluteRoot, digest: `sha256:${hash.digest("hex")}`, ok: diagnostics.length === 0, diagnostics };
+}
+export {
+  verifyPlatformRepository
+};

package/dist/platform/workset.d.ts

@@ -0,0 +1,21 @@
+import { type Inventory, type PlatformProfile, type WorksetPlan, type WorksetReceipt, type WorksetSelection } from './schemas.js';
+export interface GitRunner {
+    run(cwd: string, args: string[]): string;
+}
+export interface RemoteObserver {
+    observe(url: string, branch: string): string;
+    isAncestor(url: string, base: string, target: string): boolean;
+}
+export interface PlanWorksetInput {
+    root: string;
+    inventoryPath: string;
+    inventoryDigest: string;
+    inventory: Inventory;
+    profiles?: PlatformProfile[];
+    selection?: Partial<WorksetSelection>;
+    git?: GitRunner;
+    remote?: RemoteObserver;
+}
+export declare function planPlatformWorkset(input: PlanWorksetInput): WorksetPlan;
+export declare function applyPlatformWorkset(plan: WorksetPlan, git?: GitRunner, remote?: RemoteObserver): WorksetReceipt;
+export declare function readWorksetReceipt(path: string): WorksetReceipt;

package/dist/platform/workset.js

@@ -0,0 +1,102 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+import { worksetReceiptSchema } from "./schemas.js";
+import { resolveProfileProjects } from "./inventory.js";
+const systemGit = { run: (cwd, args) => execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim() };
+const systemRemote = { observe: (url, branch) => {
+  const output = execFileSync("git", ["ls-remote", "--exit-code", url, `refs/heads/${branch}`], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+  const commit = output.split(/\s+/u)[0];
+  if (!commit) throw new Error(`Remote branch ${branch} was not found at ${url}.`);
+  return commit;
+}, isAncestor: (url, base, target) => {
+  const temporary = mkdtempSync(resolve(tmpdir(), "platform-workset-"));
+  try {
+    execFileSync("git", ["init", "--bare", temporary], { stdio: "ignore" });
+    execFileSync("git", ["fetch", "--quiet", "--filter=blob:none", "--no-tags", url, target], { cwd: temporary, stdio: "ignore" });
+    execFileSync("git", ["merge-base", "--is-ancestor", base, target], { cwd: temporary, stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  } finally {
+    rmSync(temporary, { recursive: true, force: true });
+  }
+} };
+const digest = (value) => `sha256:${createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
+const normalizedRemote = (url) => url.replace(/^git@github\.com:/u, "https://github.com/").replace(/\.git$/u, "").toLowerCase();
+function safePath(root, slug) {
+  const path = resolve(root, "packages", slug);
+  if (!path.startsWith(`${resolve(root)}/packages/`)) throw new Error(`Project ${slug} escapes packages/.`);
+  return path;
+}
+function inspectCheckout(entry, git, remote) {
+  if (!existsSync(entry.path)) return { ...entry, action: "clone", blockers: [] };
+  const blockers = [];
+  if (lstatSync(entry.path).isSymbolicLink()) blockers.push("checkout_path_is_symlink");
+  try {
+    if (realpathSync(entry.path) !== entry.path) blockers.push("checkout_path_not_canonical");
+    if (normalizedRemote(git.run(entry.path, ["remote", "get-url", "origin"])) !== normalizedRemote(entry.gitUrl)) blockers.push("origin_mismatch");
+    if (git.run(entry.path, ["status", "--porcelain"])) blockers.push("checkout_dirty");
+    if (git.run(entry.path, ["branch", "--show-current"]) !== entry.branch) blockers.push("branch_mismatch");
+    const current = git.run(entry.path, ["rev-parse", "HEAD"]);
+    if (current === entry.commit) return { ...entry, action: blockers.length ? "blocked" : "noop", blockers };
+    if (!remote.isAncestor(entry.gitUrl, current, entry.commit)) blockers.push("remote_history_diverged");
+    return { ...entry, action: blockers.length ? "blocked" : "fast-forward", blockers };
+  } catch {
+    blockers.push("checkout_not_safe_git_repository");
+    return { ...entry, action: "blocked", blockers: [...new Set(blockers)] };
+  }
+}
+function planPlatformWorkset(input) {
+  const selection = { profiles: input.selection?.profiles ?? [], projects: input.selection?.projects ?? [], exclude: input.selection?.exclude ?? [] };
+  const projectCatalog = new Map(input.inventory.resources.projects.map((project) => [project.slug, project]));
+  const profileProjects = resolveProfileProjects(input.profiles ?? [], selection.profiles);
+  const requested = new Set(selection.projects.length || profileProjects.length ? [...profileProjects, ...selection.projects] : [...projectCatalog.keys()]);
+  selection.exclude.forEach((slug) => requested.delete(slug));
+  requested.delete("platform");
+  const repositories = new Map(input.inventory.resources.repositories.map((repository) => [repository.key, repository]));
+  const entries = [...requested].sort().map((slug) => {
+    const project = projectCatalog.get(slug);
+    if (!project) throw new Error(`Unknown project ${slug}.`);
+    const repository = repositories.get(project.primaryRepository);
+    if (!repository || repository.role !== "primary") throw new Error(`Project ${slug} has no primary source repository.`);
+    const branch = repository.repositoryPolicy?.stagingBranch ?? repository.defaultBranch;
+    const remote = input.remote ?? systemRemote;
+    const commit = remote.observe(repository.gitUrl, branch);
+    return inspectCheckout({ project: slug, repository: repository.key, gitUrl: repository.gitUrl, branch, commit, path: safePath(input.root, slug) }, input.git ?? systemGit, remote);
+  });
+  return { schemaVersion: "treeseed.platform-workset-plan/v1", root: resolve(input.root), inventoryPath: input.inventoryPath, inventoryDigest: input.inventoryDigest, selection, entries, ok: entries.every((entry) => entry.action !== "blocked") };
+}
+function applyPlatformWorkset(plan, git = systemGit, remote = systemRemote) {
+  if (!plan.ok || plan.entries.some((entry) => entry.action === "blocked")) throw new Error("Blocked workset plans cannot be applied.");
+  for (const entry of plan.entries) {
+    if (remote.observe(entry.gitUrl, entry.branch) !== entry.commit) throw new Error(`Remote branch moved after planning for ${entry.project}; create a new plan.`);
+  }
+  for (const entry of plan.entries) {
+    if (entry.action === "clone") {
+      mkdirSync(dirname(entry.path), { recursive: true });
+      git.run(plan.root, ["clone", "--branch", entry.branch, "--single-branch", entry.gitUrl, entry.path]);
+    } else if (entry.action === "fast-forward") {
+      git.run(entry.path, ["fetch", "origin", entry.branch]);
+      git.run(entry.path, ["merge", "--ff-only", entry.commit]);
+    }
+    const actual = git.run(entry.path, ["rev-parse", "HEAD"]);
+    if (actual !== entry.commit) throw new Error(`Checkout ${entry.project} did not converge to ${entry.commit}.`);
+  }
+  const receipt = worksetReceiptSchema.parse({ schemaVersion: "treeseed.platform-workset-receipt/v1", planDigest: digest(plan), inventoryDigest: plan.inventoryDigest, entries: plan.entries.map(({ blockers: _blockers, ...entry }) => ({ ...entry, action: entry.action === "blocked" ? "noop" : entry.action })) });
+  const receiptPath = resolve(plan.root, ".treeseed", "worksets", `${receipt.planDigest.slice("sha256:".length)}.json`);
+  mkdirSync(dirname(receiptPath), { recursive: true });
+  writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}
+`, { mode: 384 });
+  return receipt;
+}
+function readWorksetReceipt(path) {
+  return worksetReceiptSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+export {
+  applyPlatformWorkset,
+  planPlatformWorkset,
+  readWorksetReceipt
+};

package/dist/security/encrypted-envelope.d.ts

@@ -12,27 +12,27 @@ export declare const encryptedEnvelopeAadSchema: z.ZodObject<{
     eventType: z.ZodOptional<z.ZodString>;
     schemaVersion: z.ZodString;
 }, "strict", z.ZodTypeAny, {
+    schemaVersion: string;
     purpose: string;
     resourceType: string;
     resourceId: string;
-    schemaVersion: string;
     teamId?: string | undefined;
+    assignmentId?: string | undefined;
     topicId?: string | undefined;
     sendId?: string | undefined;
     invocationId?: string | undefined;
-    assignmentId?: string | undefined;
     sequence?: number | undefined;
     eventType?: string | undefined;
 }, {
+    schemaVersion: string;
     purpose: string;
     resourceType: string;
     resourceId: string;
-    schemaVersion: string;
     teamId?: string | undefined;
+    assignmentId?: string | undefined;
     topicId?: string | undefined;
     sendId?: string | undefined;
     invocationId?: string | undefined;
-    assignmentId?: string | undefined;
     sequence?: number | undefined;
     eventType?: string | undefined;
 }>;
@@ -81,27 +81,27 @@ export declare const encryptedEnvelopeSchema: z.ZodObject<{
         eventType: z.ZodOptional<z.ZodString>;
         schemaVersion: z.ZodString;
     }, "strict", z.ZodTypeAny, {
+        schemaVersion: string;
         purpose: string;
         resourceType: string;
         resourceId: string;
-        schemaVersion: string;
         teamId?: string | undefined;
+        assignmentId?: string | undefined;
         topicId?: string | undefined;
         sendId?: string | undefined;
         invocationId?: string | undefined;
-        assignmentId?: string | undefined;
         sequence?: number | undefined;
         eventType?: string | undefined;
     }, {
+        schemaVersion: string;
         purpose: string;
         resourceType: string;
         resourceId: string;
-        schemaVersion: string;
         teamId?: string | undefined;
+        assignmentId?: string | undefined;
         topicId?: string | undefined;
         sendId?: string | undefined;
         invocationId?: string | undefined;
-        assignmentId?: string | undefined;
         sequence?: number | undefined;
         eventType?: string | undefined;
     }>;
@@ -110,6 +110,7 @@ export declare const encryptedEnvelopeSchema: z.ZodObject<{
     createdAt: z.ZodString;
 }, "strict", z.ZodTypeAny, {
     schemaVersion: "treeseed.encrypted-envelope/v1";
+    createdAt: string;
     algorithm: "aes-256-gcm";
     keyProvider: string;
     keyId: string;
@@ -125,23 +126,23 @@ export declare const encryptedEnvelopeSchema: z.ZodObject<{
         ciphertext: string;
     };
     aad: {
+        schemaVersion: string;
         purpose: string;
         resourceType: string;
         resourceId: string;
-        schemaVersion: string;
         teamId?: string | undefined;
+        assignmentId?: string | undefined;
         topicId?: string | undefined;
         sendId?: string | undefined;
         invocationId?: string | undefined;
-        assignmentId?: string | undefined;
         sequence?: number | undefined;
         eventType?: string | undefined;
     };
     aadDigest: string;
     ciphertextDigest: string;
-    createdAt: string;
 }, {
     schemaVersion: "treeseed.encrypted-envelope/v1";
+    createdAt: string;
     algorithm: "aes-256-gcm";
     keyProvider: string;
     keyId: string;
@@ -157,21 +158,20 @@ export declare const encryptedEnvelopeSchema: z.ZodObject<{
         ciphertext: string;
     };
     aad: {
+        schemaVersion: string;
         purpose: string;
         resourceType: string;
         resourceId: string;
-        schemaVersion: string;
         teamId?: string | undefined;
+        assignmentId?: string | undefined;
         topicId?: string | undefined;
         sendId?: string | undefined;
         invocationId?: string | undefined;
-        assignmentId?: string | undefined;
         sequence?: number | undefined;
         eventType?: string | undefined;
     };
     aadDigest: string;
     ciphertextDigest: string;
-    createdAt: string;
 }>;
 export type EncryptedEnvelopeAad = z.infer<typeof encryptedEnvelopeAadSchema>;
 export type EncryptedEnvelope = z.infer<typeof encryptedEnvelopeSchema>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@treeseed/sdk",
-  "version": "0.13.0-rc.60",
+  "version": "0.13.0-rc.62",
   "description": "Portable TreeSeed contracts, standards, and typed remote control-plane clients.",
   "license": "Apache-2.0",
   "repository": {
@@ -62,6 +62,10 @@
     "vitest": "^4.1.2"
   },
   "exports": {
+    "./platform": {
+      "types": "./dist/platform/index.d.ts",
+      "default": "./dist/platform/index.js"
+    },
     "./security": {
       "types": "./dist/security/index.d.ts",
       "default": "./dist/security/index.js"