@treeseed/sdk 0.1.2 → 0.3.1

package/dist/operations/services/template-registry.js

@@ -0,0 +1,407 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, relative, resolve } from "node:path";
+import {
+  RemoteTemplateCatalogClient
+} from "@treeseed/sdk";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import {
+  resolveTreeseedTemplateCatalogCachePath,
+  resolveTreeseedTemplateCatalogEndpoint
+} from "./config-runtime.js";
+import {
+  cliPackageVersion,
+  corePackageVersion,
+  localTemplateArtifactsRoot
+} from "./runtime-paths.js";
+const TEMPLATE_CATEGORIES = ["starter", "example", "fixture", "reference-app"];
+function loadJsonFile(filePath) {
+  return JSON.parse(readFileSync(filePath, "utf8"));
+}
+function ensureDir(filePath) {
+  mkdirSync(dirname(filePath), { recursive: true });
+}
+function listFiles(root) {
+  if (!existsSync(root)) {
+    return [];
+  }
+  const files = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    const fullPath = resolve(root, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...listFiles(fullPath));
+      continue;
+    }
+    files.push(fullPath);
+  }
+  return files;
+}
+function listTemplateArtifactIds() {
+  if (!existsSync(localTemplateArtifactsRoot)) {
+    return [];
+  }
+  return readdirSync(localTemplateArtifactsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort((left, right) => left.localeCompare(right, void 0, { sensitivity: "base" }));
+}
+function isTextFile(filePath) {
+  return !/\.(png|jpe?g|gif|webp|ico|woff2?|ttf|eot|pdf|zip|gz)$/iu.test(filePath);
+}
+function validateTemplateProductShape(product) {
+  if (!product.id || !product.displayName || !product.description || !product.summary) {
+    throw new Error(`Template product ${product.id || "(unknown)"} is missing required identity metadata.`);
+  }
+  if (!TEMPLATE_CATEGORIES.includes(product.category)) {
+    throw new Error(`Template product ${product.id} uses unsupported category "${product.category}".`);
+  }
+  if (product.status !== "draft" && product.status !== "live" && product.status !== "archived") {
+    throw new Error(`Template product ${product.id} uses unsupported status "${product.status}".`);
+  }
+  if (!existsSync(product.artifactManifestPath)) {
+    throw new Error(`Template product ${product.id} points to a missing artifact manifest: ${product.artifactManifestPath}`);
+  }
+  if (!existsSync(product.templateRoot)) {
+    throw new Error(`Template product ${product.id} points to a missing template payload: ${product.templateRoot}`);
+  }
+}
+function validateTemplateManifest(definition) {
+  const { manifest, templateRoot, manifestPath, product } = definition;
+  if (!TEMPLATE_CATEGORIES.includes(manifest.category)) {
+    throw new Error(`Invalid template category in ${manifestPath}: ${manifest.category}`);
+  }
+  if (!manifest.id || !manifest.displayName || !manifest.description) {
+    throw new Error(`Template manifest ${manifestPath} is missing required metadata fields.`);
+  }
+  if (manifest.id !== product.id) {
+    throw new Error(`Template product ${product.id} does not match artifact id ${manifest.id}.`);
+  }
+  if (!existsSync(templateRoot)) {
+    throw new Error(`Template ${manifest.id} is missing template/ at ${templateRoot}.`);
+  }
+  validateTemplatePlaceholders(definition);
+}
+function validateTemplatePlaceholders(definition) {
+  const declaredTokens = new Set(definition.manifest.variables.map((variable) => variable.token));
+  const discoveredTokens = /* @__PURE__ */ new Set();
+  for (const filePath of listFiles(definition.templateRoot)) {
+    if (!isTextFile(filePath)) {
+      continue;
+    }
+    const contents = readFileSync(filePath, "utf8");
+    for (const match of contents.matchAll(/__[A-Z0-9_]+__/g)) {
+      discoveredTokens.add(match[0]);
+    }
+  }
+  for (const token of discoveredTokens) {
+    if (!declaredTokens.has(token)) {
+      throw new Error(`Template ${definition.manifest.id} uses undeclared token ${token}.`);
+    }
+  }
+}
+function normalizeTemplateProduct(remoteProduct) {
+  const artifactRoot = resolve(localTemplateArtifactsRoot, remoteProduct.id);
+  return {
+    ...remoteProduct,
+    contentPath: `${remoteProduct.fulfillment.source.repoUrl}#${remoteProduct.id}`,
+    artifactRoot,
+    artifactManifestPath: resolve(artifactRoot, "template.config.json"),
+    templateRoot: resolve(artifactRoot, "template")
+  };
+}
+function readTemplateCatalogCache(cachePath) {
+  if (!existsSync(cachePath)) {
+    return null;
+  }
+  return loadJsonFile(cachePath);
+}
+function writeTemplateCatalogCache(cachePath, endpoint, response) {
+  ensureDir(cachePath);
+  const payload = {
+    endpoint,
+    fetchedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    items: response.items
+  };
+  writeFileSync(cachePath, `${JSON.stringify(payload, null, 2)}
+`, "utf8");
+}
+async function loadRemoteTemplateCatalog(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const env = options.env ?? process.env;
+  const endpoint = resolveTreeseedTemplateCatalogEndpoint(cwd, env);
+  const cachePath = resolveTreeseedTemplateCatalogCachePath(cwd);
+  try {
+    const response = await new RemoteTemplateCatalogClient({ endpoint }).listTemplates();
+    writeTemplateCatalogCache(cachePath, endpoint, response);
+    return {
+      items: response.items,
+      endpoint,
+      usedCache: false
+    };
+  } catch (error) {
+    const cached = readTemplateCatalogCache(cachePath);
+    if (!cached) {
+      throw error;
+    }
+    options.writeWarning?.(
+      `Using cached template catalog from ${cached.fetchedAt} because the remote endpoint could not be reached.`
+    );
+    return {
+      items: cached.items,
+      endpoint: cached.endpoint,
+      usedCache: true
+    };
+  }
+}
+function loadTemplateState(siteRoot) {
+  const statePath = resolve(siteRoot, ".treeseed", "template-state.json");
+  if (!existsSync(statePath)) {
+    throw new Error(`Template state is missing at ${statePath}. This site may not have been created from a Treeseed template.`);
+  }
+  return loadJsonFile(statePath);
+}
+function writeTemplateState(siteRoot, state) {
+  const statePath = resolve(siteRoot, ".treeseed", "template-state.json");
+  ensureDir(statePath);
+  writeFileSync(statePath, `${JSON.stringify(state, null, 2)}
+`, "utf8");
+}
+function toTitleCase(value) {
+  return value.split(/[-_\s]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+function inferSlug(target, explicitSlug) {
+  return (explicitSlug ?? target).toLowerCase().replace(/[^a-z0-9-]+/g, "-");
+}
+function inferName(target, explicitName) {
+  return explicitName ?? toTitleCase(target);
+}
+function resolveVariableValue(variable, input) {
+  switch (variable.deriveFrom) {
+    case "slug":
+      return inferSlug(input.target, input.slug);
+    case "name":
+      return inferName(input.target, input.name);
+    case "siteUrl":
+      return input.siteUrl ?? variable.default ?? "";
+    case "contactEmail":
+      return input.contactEmail ?? variable.default ?? "";
+    case "repositoryUrl":
+      return input.repositoryUrl ?? variable.default ?? "";
+    case "discordUrl":
+      return input.discordUrl ?? variable.default ?? "";
+    case "cliVersion":
+      return `^${cliPackageVersion}`;
+    case "coreVersion":
+      return `^${corePackageVersion}`;
+    default:
+      return variable.default ?? "";
+  }
+}
+function applyReplacements(source, replacements) {
+  let output = source;
+  for (const [token, value] of Object.entries(replacements)) {
+    output = output.split(token).join(value);
+  }
+  return output;
+}
+function renderTemplateFile(filePath, replacements) {
+  return applyReplacements(readFileSync(filePath, "utf8"), replacements);
+}
+function copyTemplateTree(templateRoot, targetRoot, replacements) {
+  for (const filePath of listFiles(templateRoot)) {
+    const relativePath = relative(templateRoot, filePath);
+    const outputPath = resolve(targetRoot, relativePath);
+    ensureDir(outputPath);
+    if (isTextFile(filePath)) {
+      writeFileSync(outputPath, renderTemplateFile(filePath, replacements), "utf8");
+      continue;
+    }
+    cpSync(filePath, outputPath, { recursive: false });
+  }
+}
+function syncManagedPackageJson(targetPath, sourcePath, replacements, check) {
+  const currentJson = existsSync(targetPath) ? loadJsonFile(targetPath) : {};
+  const templateJson = JSON.parse(renderTemplateFile(sourcePath, replacements));
+  const nextJson = {
+    ...currentJson,
+    type: templateJson.type ?? currentJson.type,
+    scripts: typeof templateJson.scripts === "object" && templateJson.scripts !== null ? { ...currentJson.scripts ?? {}, ...templateJson.scripts } : currentJson.scripts,
+    dependencies: {
+      ...currentJson.dependencies ?? {},
+      ...Object.fromEntries(
+        Object.entries(templateJson.dependencies ?? {}).filter(([name]) => name.startsWith("@treeseed/"))
+      )
+    }
+  };
+  const currentSerialized = `${JSON.stringify(currentJson, null, 2)}
+`;
+  const nextSerialized = `${JSON.stringify(nextJson, null, 2)}
+`;
+  if (currentSerialized === nextSerialized) {
+    return false;
+  }
+  if (!check) {
+    writeFileSync(targetPath, nextSerialized, "utf8");
+  }
+  return true;
+}
+function validateYamlFile(filePath) {
+  parseYaml(readFileSync(filePath, "utf8"));
+}
+async function listTemplateProducts(options = {}) {
+  const remoteCatalog = await loadRemoteTemplateCatalog(options);
+  return remoteCatalog.items.map((entry) => normalizeTemplateProduct(entry)).sort((left, right) => {
+    const featuredDiff = Number(Boolean(right.featured)) - Number(Boolean(left.featured));
+    if (featuredDiff !== 0) {
+      return featuredDiff;
+    }
+    return left.displayName.localeCompare(right.displayName, void 0, { sensitivity: "base" });
+  });
+}
+async function resolveTemplateProduct(id, options = {}) {
+  const product = (await listTemplateProducts(options)).find((entry) => entry.id === id);
+  if (!product) {
+    throw new Error(`Unable to resolve remote template product "${id}".`);
+  }
+  return product;
+}
+async function resolveTemplateDefinition(id, options = {}, category) {
+  const product = await resolveTemplateProduct(id, options);
+  if (category && product.category !== category) {
+    throw new Error(`Unable to resolve template "${id}" in category "${category}".`);
+  }
+  validateTemplateProductShape(product);
+  const manifest = loadJsonFile(product.artifactManifestPath);
+  const definition = {
+    product,
+    manifestPath: product.artifactManifestPath,
+    templateRoot: product.templateRoot,
+    manifest
+  };
+  validateTemplateManifest(definition);
+  return definition;
+}
+async function validateTemplateProduct(product, options = {}) {
+  const definition = await resolveTemplateDefinition(product.id, options);
+  if (definition.manifest.templateApiVersion !== definition.product.templateApiVersion) {
+    throw new Error(`Template product ${definition.product.id} and artifact templateApiVersion do not match.`);
+  }
+  if ((definition.manifest.templateVersion ?? "") && definition.manifest.templateVersion !== definition.product.templateVersion) {
+    throw new Error(`Template product ${definition.product.id} and artifact templateVersion do not match.`);
+  }
+  if (definition.manifest.minCliVersion !== definition.product.minCliVersion) {
+    throw new Error(`Template product ${definition.product.id} and artifact minCliVersion do not match.`);
+  }
+  if ((definition.manifest.minCoreVersion ?? "") && definition.manifest.minCoreVersion !== definition.product.minCoreVersion) {
+    throw new Error(`Template product ${definition.product.id} and artifact minCoreVersion do not match.`);
+  }
+  return definition;
+}
+async function validateAllTemplateDefinitions(options = {}) {
+  const ids = listTemplateArtifactIds();
+  return Promise.all(ids.map((id) => validateTemplateProduct({ id }, options)));
+}
+function buildTemplateReplacements(manifest, input) {
+  const replacements = {};
+  for (const variable of manifest.variables) {
+    const value = resolveVariableValue(variable, input);
+    if (variable.required && !value) {
+      throw new Error(`Template "${manifest.id}" requires a value for "${variable.name}".`);
+    }
+    replacements[variable.token] = value;
+  }
+  return replacements;
+}
+async function scaffoldTemplateProject(templateId, targetRoot, input, options = {}) {
+  const definition = await resolveTemplateDefinition(templateId, options);
+  const replacements = buildTemplateReplacements(definition.manifest, {
+    ...input,
+    target: basename(targetRoot)
+  });
+  copyTemplateTree(definition.templateRoot, targetRoot, replacements);
+  writeTemplateState(targetRoot, {
+    templateId: definition.product.id,
+    templateVersion: definition.product.templateVersion,
+    sourceRef: definition.product.fulfillment.source.ref,
+    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    lastSyncedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    replacements
+  });
+  return definition.product;
+}
+async function syncTemplateProject(siteRoot, options = {}) {
+  const check = options.check === true;
+  const state = loadTemplateState(siteRoot);
+  const definition = await resolveTemplateDefinition(state.templateId, options);
+  const managedSurface = definition.manifest.managedSurface ?? {};
+  const changes = [];
+  for (const relativePath of managedSurface.coreManaged ?? []) {
+    const targetPath = resolve(siteRoot, relativePath);
+    const sourcePath = resolve(definition.templateRoot, relativePath);
+    if (!existsSync(sourcePath)) {
+      throw new Error(`Managed template file is missing from artifact: ${relativePath}`);
+    }
+    if (relativePath === "package.json") {
+      if (syncManagedPackageJson(targetPath, sourcePath, state.replacements, check)) {
+        changes.push(relativePath);
+      }
+      continue;
+    }
+    const nextContent = renderTemplateFile(sourcePath, state.replacements);
+    const currentContent = existsSync(targetPath) ? readFileSync(targetPath, "utf8") : "";
+    if (currentContent === nextContent) {
+      continue;
+    }
+    if (!check) {
+      ensureDir(targetPath);
+      writeFileSync(targetPath, nextContent, "utf8");
+    }
+    changes.push(relativePath);
+  }
+  for (const relativePath of managedSurface.validatedOnly ?? []) {
+    const targetPath = resolve(siteRoot, relativePath);
+    if (!existsSync(targetPath)) {
+      throw new Error(`Validated file is missing from generated site: ${relativePath}`);
+    }
+    validateYamlFile(targetPath);
+  }
+  if (!check) {
+    writeTemplateState(siteRoot, {
+      ...state,
+      templateVersion: definition.product.templateVersion,
+      sourceRef: definition.product.fulfillment.source.ref,
+      lastSyncedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  return changes;
+}
+function serializeTemplateRegistryEntry(product) {
+  return {
+    id: product.id,
+    displayName: product.displayName,
+    description: product.description,
+    summary: product.summary,
+    status: product.status,
+    featured: Boolean(product.featured),
+    category: product.category,
+    tags: product.tags ?? [],
+    publisher: product.publisher,
+    templateVersion: product.templateVersion,
+    templateApiVersion: product.templateApiVersion,
+    minCliVersion: product.minCliVersion,
+    minCoreVersion: product.minCoreVersion,
+    source: product.fulfillment.source
+  };
+}
+async function exportTemplateCatalogYaml(options = {}) {
+  return stringifyYaml((await listTemplateProducts(options)).map(serializeTemplateRegistryEntry));
+}
+export {
+  TEMPLATE_CATEGORIES,
+  buildTemplateReplacements,
+  exportTemplateCatalogYaml,
+  listTemplateProducts,
+  resolveTemplateDefinition,
+  resolveTemplateProduct,
+  scaffoldTemplateProject,
+  serializeTemplateRegistryEntry,
+  syncTemplateProject,
+  validateAllTemplateDefinitions,
+  validateTemplateProduct
+};

package/dist/operations/services/watch-dev.d.ts

@@ -0,0 +1,21 @@
+export declare function isEditablePackageWorkspace(): boolean;
+export declare function workspaceSdkRoot(): string | null;
+export declare function writeDevReloadStamp(projectRoot: any): void;
+export declare function readDevReloadState(projectRoot: any): any;
+export declare function createTenantWatchEntries(tenantRoot: any): {
+    kind: string;
+    root: string;
+}[];
+export declare function startPollingWatch({ watchEntries, onChange }: {
+    watchEntries: any;
+    onChange: any;
+}): () => void;
+export declare function stopManagedProcess(child: any, signal?: string): Promise<void>;
+export declare function createWatchBuildPaths(projectRoot: any): {
+    watchRoot: string;
+    stagedDistRoot: string;
+    backupDistRoot: string;
+    liveDistRoot: string;
+};
+export declare function swapStagedBuildOutput(projectRoot: any): void;
+export declare function clearStagedBuildOutput(projectRoot: any): void;