@treeseed/sdk 0.1.2 → 0.3.1

package/dist/scripts/ensure-mailpit.js

@@ -0,0 +1,29 @@
+import { spawnSync } from 'node:child_process';
+import { dockerIsAvailable, findRunningMailpitContainer } from '../operations/services/mailpit-runtime.js';
+import { mailpitComposeFile, packageRoot } from '../operations/services/runtime-paths.js';
+if (!dockerIsAvailable()) {
+    console.error('Docker is required for Treeseed form email testing. Start Docker and rerun the Mailpit command.');
+    process.exit(1);
+}
+const existingMailpit = findRunningMailpitContainer();
+if (existingMailpit) {
+    console.log(`Reusing existing Mailpit container "${existingMailpit.name}" on ports 1025 and 8025.`);
+    process.exit(0);
+}
+const result = spawnSync('docker', ['compose', '-f', mailpitComposeFile, 'up', '-d', 'mailpit'], {
+    encoding: 'utf8',
+    cwd: packageRoot,
+    env: { ...process.env },
+});
+if (result.status !== 0) {
+    const reusedMailpit = findRunningMailpitContainer();
+    if (reusedMailpit) {
+        console.log(`Reusing existing Mailpit container "${reusedMailpit.name}" on ports 1025 and 8025.`);
+        process.exit(0);
+    }
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+}
+process.exit(result.status ?? 1);

package/dist/scripts/local-dev.js

@@ -0,0 +1,129 @@
+import { spawnSync } from 'node:child_process';
+import { corePackageRoot } from '../operations/services/runtime-tools.js';
+import { fixtureRoot } from '../operations/services/runtime-paths.js';
+import { prepareCloudflareLocalRuntime, startWranglerDev } from '../operations/services/local-dev.js';
+import { clearStagedBuildOutput, createWatchBuildPaths, createTenantWatchEntries, startPollingWatch, stopManagedProcess, swapStagedBuildOutput, writeDevReloadStamp, workspaceSdkRoot, } from '../operations/services/watch-dev.js';
+const cliArgs = process.argv.slice(2);
+const watchMode = cliArgs.includes('--watch');
+const wranglerArgs = cliArgs.filter((arg) => arg !== '--watch');
+let wranglerChild = null;
+let stopWatching = null;
+let isStoppingForRebuild = false;
+let shuttingDown = false;
+function runStep(command, args, { cwd = corePackageRoot, env = {}, fatal = true } = {}) {
+    const result = spawnSync(command, args, {
+        stdio: 'inherit',
+        cwd,
+        env: { ...process.env, ...env },
+    });
+    if (result.status !== 0 && fatal) {
+        process.exit(result.status ?? 1);
+    }
+    return result.status === 0;
+}
+function runFixtureBuildCycle({ includePackageBuild = false, includeSdkBuild = false, fatal = true, stagedOutput = false } = {}) {
+    if (includeSdkBuild) {
+        const sdkRoot = workspaceSdkRoot();
+        if (sdkRoot) {
+            const built = runStep('npm', ['run', 'build:dist'], { cwd: sdkRoot, fatal });
+            if (!built) {
+                return false;
+            }
+        }
+    }
+    if (includePackageBuild) {
+        const built = runStep('npm', ['run', 'build:dist'], { cwd: corePackageRoot, fatal });
+        if (!built) {
+            return false;
+        }
+    }
+    if (watchMode) {
+        writeDevReloadStamp(fixtureRoot);
+    }
+    try {
+        const outDir = stagedOutput ? createWatchBuildPaths(fixtureRoot).stagedDistRoot : undefined;
+        if (stagedOutput) {
+            clearStagedBuildOutput(fixtureRoot);
+        }
+        prepareCloudflareLocalRuntime({
+            envOverrides: watchMode ? { TREESEED_PUBLIC_DEV_WATCH_RELOAD: 'true' } : {},
+            outDir,
+        });
+        if (stagedOutput) {
+            swapStagedBuildOutput(fixtureRoot);
+        }
+        return true;
+    }
+    catch (error) {
+        if (fatal) {
+            throw error;
+        }
+        console.error(error instanceof Error ? error.message : String(error));
+        return false;
+    }
+}
+function startWrangler() {
+    const child = startWranglerDev(wranglerArgs, {
+        env: watchMode ? { TREESEED_PUBLIC_DEV_WATCH_RELOAD: 'true' } : {},
+        detached: process.platform !== 'win32',
+    });
+    wranglerChild = child;
+    child.on('exit', (code, signal) => {
+        if (child !== wranglerChild) {
+            return;
+        }
+        wranglerChild = null;
+        if (isStoppingForRebuild || shuttingDown) {
+            return;
+        }
+        if (stopWatching) {
+            stopWatching();
+        }
+        if (signal) {
+            process.kill(process.pid, signal);
+            return;
+        }
+        process.exit(code ?? 0);
+    });
+}
+async function shutdownAndExit(code = 0) {
+    shuttingDown = true;
+    if (stopWatching) {
+        stopWatching();
+    }
+    await stopManagedProcess(wranglerChild);
+    process.exit(code);
+}
+process.on('SIGINT', () => {
+    void shutdownAndExit(130);
+});
+process.on('SIGTERM', () => {
+    void shutdownAndExit(143);
+});
+runFixtureBuildCycle({ includeSdkBuild: true, includePackageBuild: true, fatal: true });
+startWrangler();
+if (watchMode) {
+    console.log('Starting fixture watch mode. Changes will rebuild the package fixture and refresh the browser.');
+    stopWatching = startPollingWatch({
+        watchEntries: createTenantWatchEntries(fixtureRoot),
+        onChange: async ({ changedPaths, packageChanged, sdkChanged }) => {
+            console.log(`Detected ${changedPaths.length} change${changedPaths.length === 1 ? '' : 's'}; rebuilding ${sdkChanged ? 'sdk, core, and fixture' : packageChanged ? 'core and fixture' : 'fixture'} output...`);
+            isStoppingForRebuild = true;
+            await stopManagedProcess(wranglerChild);
+            isStoppingForRebuild = false;
+            const ok = runFixtureBuildCycle({
+                includeSdkBuild: sdkChanged,
+                includePackageBuild: packageChanged || sdkChanged,
+                fatal: false,
+                stagedOutput: false,
+            });
+            if (ok) {
+                startWrangler();
+                console.log('Rebuild complete. Wrangler restarted with the updated fixture output.');
+            }
+            else {
+                console.error('Rebuild failed. Wrangler remains stopped until the next successful save.');
+            }
+        },
+    });
+}

package/dist/scripts/logs-mailpit.js

@@ -0,0 +1,2 @@
+import { streamKnownMailpitLogs } from '../operations/services/mailpit-runtime.js';
+streamKnownMailpitLogs();

package/dist/scripts/patch-starlight-content-path.js

@@ -0,0 +1,172 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { packageRoot } from '../operations/services/runtime-paths.js';
+const legacyDocsRoot = path.resolve(packageRoot, '../..');
+const candidateStarlightRoots = [
+    path.join(process.cwd(), 'node_modules/@astrojs/starlight'),
+    path.join(packageRoot, 'node_modules/@astrojs/starlight'),
+    path.join(legacyDocsRoot, 'node_modules/@astrojs/starlight'),
+];
+const candidateCollectionFiles = [
+    path.join(process.cwd(), 'node_modules/@astrojs/starlight/utils/collection.ts'),
+    path.join(packageRoot, 'node_modules/@astrojs/starlight/utils/collection.ts'),
+    path.join(legacyDocsRoot, 'node_modules/@astrojs/starlight/utils/collection.ts'),
+];
+const originalSource = `export type StarlightCollection = 'docs' | 'i18n';
+
+/**
+ * We still rely on the content collection folder structure to be fixed for now:
+ *
+ * - At build time, if the feature is enabled, we get all the last commit dates for each file in
+ *   the docs folder ahead of time. In the current approach, we cannot know at this time the
+ *   user-defined content folder path in the integration context as this would only be available
+ *   from the loader. A potential solution could be to do that from a custom loader re-implementing
+ *   the glob loader or built on top of it. Although, we don't have access to the Starlight
+ *   configuration from the loader to even know we should do that.
+ * - Remark plugins get passed down an absolute path to a content file and we need to figure out
+ *   the language from that path. Without knowing the content folder path, we cannot reliably do
+ *   so.
+ *
+ * Below are various functions to easily get paths to these collections and avoid having to
+ * hardcode them throughout the codebase. When user-defined content folder locations are supported,
+ * these helper functions should be updated to reflect that in one place.
+ */
+
+export function getCollectionUrl(collection: StarlightCollection, srcDir: URL) {
+\treturn new URL(\`content/\${collection}/\`, srcDir);
+}
+
+export function getCollectionPathFromRoot(
+\tcollection: StarlightCollection,
+\t{ root, srcDir }: { root: URL | string; srcDir: URL | string }
+) {
+\treturn (
+\t\t(typeof srcDir === 'string' ? srcDir : srcDir.pathname).replace(
+\t\t\ttypeof root === 'string' ? root : root.pathname,
+\t\t\t''
+\t\t) +
+\t\t'content/' +
+\t\tcollection
+\t);
+}
+`;
+const patchedSource = `export type StarlightCollection = 'docs' | 'i18n';
+
+/**
+ * We still rely on the content collection folder structure to be fixed for now:
+ *
+ * - At build time, if the feature is enabled, we get all the last commit dates for each file in
+ *   the docs folder ahead of time. In the current approach, we cannot know at this time the
+ *   user-defined content folder path in the integration context as this would only be available
+ *   from the loader. A potential solution could be to do that from a custom loader re-implementing
+ *   the glob loader or built on top of it. Although, we don't have access to the Starlight
+ *   configuration from the loader to even know we should do that.
+ * - Remark plugins get passed down an absolute path to a content file and we need to figure out
+ *   the language from that path. Without knowing the content folder path, we cannot reliably do
+ *   so.
+ *
+ * Below are various functions to easily get paths to these collections and avoid having to
+ * hardcode them throughout the codebase. When user-defined content folder locations are supported,
+ * these helper functions should be updated to reflect that in one place.
+ */
+
+export function getCollectionUrl(collection: StarlightCollection, srcDir: URL) {
+\treturn new URL(\`content/\${getCollectionDir(collection)}/\`, srcDir);
+}
+
+function getCollectionDir(collection: StarlightCollection) {
+\treturn collection === 'docs' ? 'knowledge' : collection;
+}
+
+export function getCollectionPathFromRoot(
+\tcollection: StarlightCollection,
+\t{ root, srcDir }: { root: URL | string; srcDir: URL | string }
+) {
+\treturn (
+\t\t(typeof srcDir === 'string' ? srcDir : srcDir.pathname).replace(
+\t\t\ttypeof root === 'string' ? root : root.pathname,
+\t\t\t''
+\t\t) +
+\t\t'content/' +
+\t\tgetCollectionDir(collection)
+\t);
+}
+`;
+async function patchCollectionFile(collectionFile) {
+    const source = await fs.readFile(collectionFile, 'utf8');
+    if (source === patchedSource) {
+        return 'already';
+    }
+    if (source !== originalSource) {
+        throw new Error(`Unexpected Starlight collection helper format in ${collectionFile}`);
+    }
+    await fs.writeFile(collectionFile, patchedSource);
+    return 'patched';
+}
+async function copyVendoredTree(sourceRoot, targetRoot) {
+    const entries = await fs.readdir(sourceRoot, { withFileTypes: true });
+    for (const entry of entries) {
+        const sourcePath = path.join(sourceRoot, entry.name);
+        const targetPath = path.join(targetRoot, entry.name);
+        if (entry.isDirectory()) {
+            await fs.mkdir(targetPath, { recursive: true });
+            await copyVendoredTree(sourcePath, targetPath);
+            continue;
+        }
+        await fs.copyFile(sourcePath, targetPath);
+    }
+}
+async function patchStarlightPackageRoot(starlightRoot) {
+    const packageJsonPath = path.join(starlightRoot, 'package.json');
+    const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
+    const coreVendorRoot = path.join(path.dirname(path.dirname(starlightRoot)), '@treeseed/core/dist/vendor/starlight');
+    await copyVendoredTree(coreVendorRoot, starlightRoot);
+    packageJson.exports = {
+        ...packageJson.exports,
+        '.': './index.js',
+        './schema': './schema.js',
+        './loaders': './loaders.js',
+        './route-data': './route-data.js',
+        './internal': './internal.js',
+        './components': './components.js',
+    };
+    await fs.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`, 'utf8');
+}
+async function run() {
+    const existingFiles = [];
+    for (const collectionFile of candidateCollectionFiles) {
+        try {
+            await fs.access(collectionFile);
+            existingFiles.push(collectionFile);
+        }
+        catch {
+            // Ignore missing dependency trees.
+        }
+    }
+    if (existingFiles.length === 0) {
+        throw new Error('Unable to find any Starlight collection helper files to patch.');
+    }
+    let patchedAny = false;
+    for (const collectionFile of existingFiles) {
+        const result = await patchCollectionFile(collectionFile);
+        patchedAny = patchedAny || result === 'patched';
+    }
+    for (const starlightRoot of candidateStarlightRoots) {
+        try {
+            await fs.access(path.join(starlightRoot, 'package.json'));
+            await patchStarlightPackageRoot(starlightRoot);
+            patchedAny = true;
+        }
+        catch {
+            // Ignore missing dependency trees.
+        }
+    }
+    console.log(patchedAny
+        ? 'Applied Starlight knowledge-path patch.'
+        : 'Starlight knowledge-path patch already applied.');
+}
+run().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});

package/dist/scripts/release-verify.js

@@ -1,10 +1,11 @@
-import { readFileSync, readdirSync } from 'node:fs';
-import { extname, join, resolve } from 'node:path';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { basename, extname, join, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { packageRoot } from './package-tools.js';
+const npmCacheDir = resolve(tmpdir(), 'treeseed-npm-cache');
 const textExtensions = new Set(['.js', '.ts', '.mjs', '.cjs', '.d.js', '.json', '.md']);
 const forbiddenPatterns = [
-    /['"`]file:[^'"`\n]+['"`]/,
     /['"`]workspace:[^'"`\n]+['"`]/,
     /['"`](?:\.\.\/|\.\/)[^'"`\n]*src\/[^'"`\n]*\.(?:[cm]?js|ts|tsx|json|astro|css)['"`]/,
     /['"`][^'"`\n]*\/packages\/[^'"`\n]*\/src\/[^'"`\n]*['"`]/,
@@ -13,7 +14,11 @@ function run(command, args) {
     const result = spawnSync(command, args, {
         cwd: packageRoot,
         stdio: 'inherit',
-        env: process.env,
+        env: {
+            ...process.env,
+            npm_config_cache: npmCacheDir,
+            NPM_CONFIG_CACHE: npmCacheDir,
+        },
     });
     if (result.status !== 0) {
         process.exit(result.status ?? 1);
@@ -43,8 +48,31 @@ function scanDirectory(root) {
         }
     }
 }
-run('npm', ['run', 'fixtures:check']);
-run('npm', ['run', 'build:dist']);
+function assertCleanDistArtifacts() {
+    const forbiddenPaths = [
+        resolve(packageRoot, 'dist', 'src'),
+        resolve(packageRoot, 'dist', 'test'),
+        resolve(packageRoot, 'dist', 'vitest.config.d.ts'),
+    ];
+    for (const targetPath of forbiddenPaths) {
+        if (existsSync(targetPath)) {
+            throw new Error(`Unexpected publish artifact present in dist: ${targetPath}`);
+        }
+    }
+    for (const filePath of walkFiles(resolve(packageRoot, 'dist'))) {
+        if (filePath.endsWith('.d.js')) {
+            throw new Error(`Unexpected generated declaration runtime artifact: ${filePath}`);
+        }
+        if (basename(filePath).startsWith('.ts-run-')) {
+            throw new Error(`Unexpected temporary runtime artifact: ${filePath}`);
+        }
+        if (filePath.includes('/dist/scripts/') && filePath.endsWith('.d.js')) {
+            throw new Error(`Unexpected script declaration artifact: ${filePath}`);
+        }
+    }
+}
+run('npm', ['run', 'lint']);
 scanDirectory(resolve(packageRoot, 'dist'));
+assertCleanDistArtifacts();
 run('npm', ['run', 'test:unit']);
 run('npm', ['run', 'test:smoke']);

package/dist/scripts/run-fixture-astro-command.js

@@ -0,0 +1,18 @@
+import { spawnSync } from 'node:child_process';
+import { corePackageRoot, fixtureRoot } from '../operations/services/runtime-paths.js';
+const [command, ...rest] = process.argv.slice(2);
+if (!command) {
+    console.error('Usage: node ./scripts/run-fixture-astro-command.mjs <check|build|preview|dev> [...args]');
+    process.exit(1);
+}
+const result = spawnSync('npx', ['astro', command, '--root', fixtureRoot, ...rest], {
+    cwd: corePackageRoot,
+    stdio: 'inherit',
+    env: process.env,
+    shell: process.platform === 'win32',
+});
+if (result.error) {
+    console.error(result.error.message);
+    process.exit(1);
+}
+process.exit(result.status ?? 1);

package/dist/scripts/scaffold-site.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { scaffoldTemplateProject } from '../operations/services/template-registry.js';
+function parseArgs(argv) {
+    const args = {
+        target: null,
+        template: 'starter-basic',
+        name: null,
+        slug: null,
+        siteUrl: null,
+        contactEmail: null,
+        repositoryUrl: null,
+        discordUrl: 'https://discord.gg/example',
+    };
+    const rest = [...argv];
+    while (rest.length > 0) {
+        const current = rest.shift();
+        if (!current)
+            continue;
+        if (!args.target && !current.startsWith('--')) {
+            args.target = current;
+            continue;
+        }
+        if (current === '--template')
+            args.template = rest.shift() ?? args.template;
+        else if (current === '--name')
+            args.name = rest.shift() ?? null;
+        else if (current === '--slug')
+            args.slug = rest.shift() ?? null;
+        else if (current === '--site-url')
+            args.siteUrl = rest.shift() ?? null;
+        else if (current === '--contact-email')
+            args.contactEmail = rest.shift() ?? null;
+        else if (current === '--repo')
+            args.repositoryUrl = rest.shift() ?? null;
+        else if (current === '--discord')
+            args.discordUrl = rest.shift() ?? args.discordUrl;
+        else
+            throw new Error(`Unknown argument: ${current}`);
+    }
+    if (!args.target)
+        throw new Error('Usage: treeseed init <directory> [--template <starter-id>] [--name <site name>] [--slug <slug>] [--site-url <url>] [--contact-email <email>] [--repo <url>] [--discord <url>]');
+    return args;
+}
+const options = parseArgs(process.argv.slice(2));
+const targetRoot = resolve(process.cwd(), options.target);
+const definition = await scaffoldTemplateProject(options.template, targetRoot, {
+    target: options.target,
+    name: options.name,
+    slug: options.slug,
+    siteUrl: options.siteUrl,
+    contactEmail: options.contactEmail,
+    repositoryUrl: options.repositoryUrl,
+    discordUrl: options.discordUrl,
+}, {
+    writeWarning: (message) => console.warn(message),
+});
+console.log(`Created Treeseed tenant from ${definition.id} at ${targetRoot}`);
+console.log('Next steps:');
+console.log(`  cd ${options.target}`);
+console.log('  npm install');
+console.log('  treeseed template show starter-basic');
+console.log('  treeseed sync --check');
+console.log('  treeseed config --environment local');
+console.log('  treeseed dev');

package/dist/scripts/stop-mailpit.js

@@ -0,0 +1,5 @@
+import { stopKnownMailpitContainers } from '../operations/services/mailpit-runtime.js';
+if (!stopKnownMailpitContainers()) {
+    process.exit(1);
+}
+console.log('Mailpit is stopped.');

package/dist/scripts/sync-dev-vars.js

@@ -0,0 +1,6 @@
+import { applyTreeseedEnvironmentToProcess, writeTreeseedLocalEnvironmentFiles } from '../operations/services/config-runtime.js';
+const tenantRoot = process.cwd();
+applyTreeseedEnvironmentToProcess({ tenantRoot, scope: 'local', override: true });
+const result = writeTreeseedLocalEnvironmentFiles(tenantRoot);
+console.log(`Wrote ${result.envLocalPath}`);
+console.log(`Wrote ${result.devVarsPath}`);

package/dist/scripts/sync-template.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { syncTemplateProject } from '../operations/services/template-registry.js';
+const args = process.argv.slice(2);
+const check = args.includes('--check');
+const changed = await syncTemplateProject(process.cwd(), {
+    check,
+    writeWarning: (message) => console.warn(message),
+});
+if (check) {
+    if (changed.length === 0) {
+        console.log('managed surface is up to date');
+    }
+    else {
+        console.log(`managed surface drift: ${changed.join(', ')}`);
+        process.exitCode = 1;
+    }
+}
+else {
+    console.log(changed.length === 0 ? 'managed surface already up to date' : `updated: ${changed.join(', ')}`);
+}

package/dist/scripts/template-catalog.test.js

@@ -0,0 +1,100 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { listTemplateProducts, resolveTemplateDefinition } from '../dist/scripts/template-registry-lib.js';
+
+function makeMachineConfigRoot(endpoint) {
+	const root = mkdtempSync(join(tmpdir(), 'treeseed-cli-template-catalog-'));
+	const configDir = resolve(root, '.treeseed', 'config');
+	mkdirSync(configDir, { recursive: true });
+	writeFileSync(resolve(configDir, 'machine.yaml'), [
+		'version: 1',
+		'settings:',
+		'  templates:',
+		`    catalogEndpoint: ${endpoint}`,
+		'',
+	].join('\n'), 'utf8');
+	return root;
+}
+
+function writeCatalogFixture(root, fileName, items) {
+	const fixturePath = resolve(root, fileName);
+	writeFileSync(fixturePath, JSON.stringify({ items }, null, 2), 'utf8');
+	return fixturePath;
+}
+
+function writeCatalogCache(root, endpoint, items) {
+	const cacheDir = resolve(root, '.treeseed', 'cache');
+	mkdirSync(cacheDir, { recursive: true });
+	writeFileSync(resolve(cacheDir, 'template-catalog.json'), JSON.stringify({
+		endpoint,
+		fetchedAt: '2026-04-08T00:00:00.000Z',
+		items,
+	}, null, 2), 'utf8');
+}
+
+const starterTemplate = {
+	id: 'starter-basic',
+	displayName: 'TreeSeed Basic',
+	description: 'Starter',
+	summary: 'Starter summary',
+	status: 'live',
+	category: 'starter',
+	publisher: {
+		id: 'treeseed',
+		name: 'TreeSeed',
+	},
+	templateVersion: '1.0.0',
+	templateApiVersion: 1,
+	minCliVersion: '0.1.1',
+	minCoreVersion: '0.1.2',
+	fulfillment: {
+		source: {
+			repoUrl: 'https://example.com/repo.git',
+			directory: 'templates/starter-basic',
+			ref: 'main',
+		},
+		hooksPolicy: 'builtin_only',
+		supportsReconcile: true,
+	},
+};
+
+test('template registry reads the remote catalog from a configured file endpoint and falls back to cache', async () => {
+	const root = mkdtempSync(join(tmpdir(), 'treeseed-cli-template-catalog-fixture-'));
+	const fixturePath = writeCatalogFixture(root, 'catalog.json', [starterTemplate]);
+	const fallbackEndpoint = 'https://127.0.0.1:9/search/templates';
+	const cwd = makeMachineConfigRoot(`file:${fixturePath}`);
+
+	const remoteProducts = await listTemplateProducts({ cwd, env: {} });
+	assert.equal(remoteProducts.length, 1);
+	assert.equal(remoteProducts[0]?.id, 'starter-basic');
+
+	writeCatalogCache(cwd, fallbackEndpoint, [starterTemplate]);
+
+	const warnings = [];
+	const cachedProducts = await listTemplateProducts({
+		cwd,
+		env: {
+			TREESEED_TEMPLATE_CATALOG_URL: fallbackEndpoint,
+		},
+		writeWarning: (message) => warnings.push(message),
+	});
+
+	assert.equal(cachedProducts.length, 1);
+	assert.equal(cachedProducts[0]?.id, 'starter-basic');
+	assert.equal(warnings.length, 1);
+	assert.match(warnings[0], /Using cached template catalog/);
+});
+
+test('template definition resolution rejects templates missing from the remote catalog', async () => {
+	const root = mkdtempSync(join(tmpdir(), 'treeseed-cli-template-catalog-empty-'));
+	const fixturePath = writeCatalogFixture(root, 'empty.json', []);
+	const cwd = makeMachineConfigRoot(`file:${fixturePath}`);
+
+	await assert.rejects(
+		() => resolveTemplateDefinition('starter-basic', { cwd, env: {} }),
+		/Unable to resolve remote template product "starter-basic"\./,
+	);
+});

package/dist/scripts/template-command.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { listTemplateProducts, resolveTemplateProduct, serializeTemplateRegistryEntry, validateTemplateProduct } from '../operations/services/template-registry.js';
+const [action = 'list', target] = process.argv.slice(2);
+const writeWarning = (message) => console.warn(message);
+switch (action) {
+    case 'list': {
+        for (const product of await listTemplateProducts({ writeWarning })) {
+            console.log(`${product.id}\t${product.displayName}\t${product.description}`);
+        }
+        break;
+    }
+    case 'show': {
+        if (!target) {
+            throw new Error('Usage: treeseed template show <id>');
+        }
+        console.log(JSON.stringify(serializeTemplateRegistryEntry(await resolveTemplateProduct(target, { writeWarning })), null, 2));
+        break;
+    }
+    case 'validate': {
+        const products = target
+            ? [await resolveTemplateProduct(target, { writeWarning })]
+            : await listTemplateProducts({ writeWarning });
+        for (const product of products) {
+            await validateTemplateProduct(product, { writeWarning });
+            console.log(`validated ${product.id}`);
+        }
+        break;
+    }
+    default:
+        throw new Error(`Unknown template action: ${action}`);
+}

package/dist/scripts/tenant-astro-command.js

@@ -0,0 +1,3 @@
+import { resolveAstroBin, runNodeBinary } from '../operations/services/runtime-tools.js';
+const args = process.argv.slice(2);
+runNodeBinary(resolveAstroBin(), args, { cwd: process.cwd() });

package/dist/scripts/tenant-build.js

@@ -0,0 +1,16 @@
+import { resolveAstroBin, createProductionBuildEnv, packageScriptPath, runNodeBinary, runNodeScript } from '../operations/services/runtime-tools.js';
+process.env.TREESEED_LOCAL_DEV_MODE = process.env.TREESEED_LOCAL_DEV_MODE ?? 'cloudflare';
+runNodeScript(packageScriptPath('patch-starlight-content-path'), [], { cwd: process.cwd() });
+runNodeScript(packageScriptPath('aggregate-book'), [], { cwd: process.cwd() });
+runNodeBinary(resolveAstroBin(), ['build'], {
+    cwd: process.cwd(),
+    env: createProductionBuildEnv({
+        TREESEED_LOCAL_DEV_MODE: process.env.TREESEED_LOCAL_DEV_MODE,
+    }),
+});
+runNodeScript(packageScriptPath('build-tenant-worker'), [], {
+    cwd: process.cwd(),
+    env: createProductionBuildEnv({
+        TREESEED_LOCAL_DEV_MODE: process.env.TREESEED_LOCAL_DEV_MODE,
+    }),
+});