@treeseed/core 0.1.2

package/README.md

@@ -0,0 +1,145 @@
+# @treeseed/core
+
+`@treeseed/core` is the Treeseed runtime package for Astro/Starlight sites. It contains the published runtime, shared components and styles, forms and deploy helpers, plugin runtime wiring, and agent-facing utilities used by Treeseed tenants.
+
+This repository is the package root. Run package commands from [`core`](./), not from the top-level `treeseed` workspace.
+
+## Requirements
+
+- Node `>=20`
+- npm `>=10`
+
+## Install
+
+For package contributors:
+
+```bash
+git submodule update --init --recursive
+npm install
+```
+
+This creates `package-lock.json`, installs dependencies, and runs the package `prepare` step to build `dist/`.
+
+For CI or any fresh reproducible checkout:
+
+```bash
+npm ci
+```
+
+## Package Layout
+
+- `src/`: package source
+- `scripts/`: build, release, and verification scripts
+- `test/`: unit tests run by Vitest
+- `.fixtures/treeseed-fixtures/`: pinned shared fixtures submodule
+- `.github/workflows/`: CI and publish workflows for this package repo
+- `templates/github/deploy.workflow.yml`: downstream tenant deploy workflow template
+
+The package builds directly against the canonical working-site fixture in `treeseed-fixtures`.
+
+## Commands
+
+### Core development
+
+```bash
+npm run fixtures:check
+npm run build:dist
+npm run test:unit
+npm run check
+npm run build
+npm run test:smoke
+```
+
+What they do:
+
+- `fixtures:check`: verifies that the pinned shared fixture is initialized and usable
+- `build:dist`: builds the publishable `dist/` package output
+- `test:unit`: runs package unit tests with Vitest
+- `check`: runs `astro check` against the internal fixture app
+- `build`: builds the internal fixture app in production-like mode
+- `test:smoke`: runs the packed-install smoke test
+
+### Full verification
+
+```bash
+npm run verify
+```
+
+`npm run verify` is an alias for `npm run release:verify`. The verification chain is:
+
+1. `npm run build:dist`
+2. `npm run test:unit`
+3. `npm run check`
+4. `npm run build`
+5. `npm run test:smoke`
+
+If this command passes, the package is in the same state expected by CI and the publish workflow.
+
+### Release commands
+
+```bash
+npm run release:check-tag -- 0.0.1
+npm run release:publish
+```
+
+- `release:check-tag` validates that a git tag matches the version in [`package.json`](./package.json)
+- `release:publish` publishes the package to npm
+
+## GitHub Actions
+
+This repo ships two package workflows:
+
+- [`ci.yml`](./.github/workflows/ci.yml): runs on push and pull request, installs with `npm ci`, then runs `npm run verify`
+- [`publish.yml`](./.github/workflows/publish.yml): runs on `workflow_dispatch` and on plain semver tags like `0.1.0`; it installs with `npm ci`, validates the tag with `release:check-tag`, runs `npm run verify`, and publishes with `NPM_TOKEN`
+
+The deploy workflow template at [`templates/github/deploy.workflow.yml`](./templates/github/deploy.workflow.yml) is for downstream Treeseed site repositories, not for publishing this package.
+
+## Consumer Contract
+
+The package publishes built artifacts from `dist/` and exposes runtime entrypoints through [`package.json`](./package.json) `exports`.
+
+The published package includes:
+
+- `dist/`
+- `tsconfigs/`
+- `templates/`
+- `style/`
+- `utils/`
+- `README.md`
+
+The package currently depends on:
+
+- `@treeseed/sdk`
+- Astro and Starlight runtime packages
+- Tailwind/Vite integration used by the site runtime
+- Wrangler for Cloudflare-oriented runtime and deploy support
+
+## Contributor Workflow
+
+Typical local workflow:
+
+```bash
+npm install
+npm run verify
+```
+
+If you only need one stage:
+
+```bash
+npm run test:unit
+npm run check
+npm run build
+```
+
+When changing exported package code, rerun `npm run build:dist` and then `npm run verify`.
+
+## Publishing
+
+Release flow for this repo:
+
+1. Update the package version in [`package.json`](./package.json).
+2. Run `npm run verify`.
+3. Create a matching tag: `<version>` such as `0.1.0`.
+4. Push the tag or run the publish workflow manually.
+
+The publish workflow expects the npm auth token in `NPM_TOKEN`.

package/dist/agents/index.js

@@ -0,0 +1,5 @@
+import { AGENT_HANDLER_REGISTRY, resolveAgentHandler } from "./registry.js";
+export {
+  AGENT_HANDLER_REGISTRY,
+  resolveAgentHandler
+};

package/dist/agents/registry-helper.js

@@ -0,0 +1,14 @@
+function defineAgentHandlerRegistry(registry) {
+  return registry;
+}
+function resolveAgentHandlerFromRegistry(registry, kind) {
+  const handler = registry[kind];
+  if (!handler) {
+    throw new Error(`No runtime handler is registered for agent handler "${kind}".`);
+  }
+  return handler;
+}
+export {
+  defineAgentHandlerRegistry,
+  resolveAgentHandlerFromRegistry
+};

package/dist/agents/registry.js

@@ -0,0 +1,88 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { resolveTreeseedTenantRoot } from "../tenant/config.js";
+import { resolveAgentRuntimeProviders } from "../utils/plugin-runtime.js";
+import { getTreeseedAgentProviderSelections } from "../deploy/runtime.js";
+const BUILTIN_HANDLER_KINDS = [
+  "planner",
+  "architect",
+  "engineer",
+  "notifier",
+  "researcher",
+  "reviewer",
+  "releaser"
+];
+const HANDLER_EXPORT_NAMES = {
+  planner: "plannerHandler",
+  architect: "architectHandler",
+  engineer: "engineerHandler",
+  notifier: "notifierHandler",
+  researcher: "researcherHandler",
+  reviewer: "reviewerHandler",
+  releaser: "releaserHandler"
+};
+function getTenantAgentHandlerModulePath(kind, tenantRoot = resolveTreeseedTenantRoot()) {
+  return resolve(tenantRoot, "src/agents", `${kind}.ts`);
+}
+async function loadTenantAgentHandlerRegistry(tenantRoot = resolveTreeseedTenantRoot()) {
+  const registry = {};
+  for (const kind of BUILTIN_HANDLER_KINDS) {
+    const modulePath = getTenantAgentHandlerModulePath(kind, tenantRoot);
+    if (!existsSync(modulePath)) {
+      continue;
+    }
+    let moduleExports;
+    try {
+      moduleExports = await import(
+        /* @vite-ignore */
+        pathToFileURL(modulePath).href
+      );
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to import tenant agent handler "${kind}" from ${modulePath}: ${reason}`);
+    }
+    const exportName = HANDLER_EXPORT_NAMES[kind];
+    const handler = moduleExports[exportName];
+    if (!handler) {
+      throw new Error(
+        `Tenant agent handler module "${modulePath}" must export "${exportName}" for handler kind "${kind}".`
+      );
+    }
+    const normalizedHandler = handler;
+    if (normalizedHandler.kind !== kind) {
+      throw new Error(
+        `Tenant agent handler "${exportName}" from "${modulePath}" declares kind "${normalizedHandler.kind}", but "${kind}" was expected.`
+      );
+    }
+    registry[kind] = normalizedHandler;
+  }
+  return registry;
+}
+const AGENT_HANDLER_REGISTRY = await loadTenantAgentHandlerRegistry();
+function listRegisteredAgentHandlers() {
+  const runtimeProviders = resolveAgentRuntimeProviders(resolveTreeseedTenantRoot(), getTreeseedAgentProviderSelections());
+  return [.../* @__PURE__ */ new Set([...Object.keys(AGENT_HANDLER_REGISTRY), ...runtimeProviders.handlers.keys()])];
+}
+function resolveAgentHandler(kind) {
+  const runtimeProviders = resolveAgentRuntimeProviders(resolveTreeseedTenantRoot(), getTreeseedAgentProviderSelections());
+  const handler = AGENT_HANDLER_REGISTRY[kind] ?? runtimeProviders.handlers.get(kind);
+  if (!handler) {
+    if (BUILTIN_HANDLER_KINDS.includes(kind)) {
+      const expectedPath = getTenantAgentHandlerModulePath(kind);
+      const expectedExport = HANDLER_EXPORT_NAMES[kind];
+      throw new Error(
+        `No runtime handler is registered for agent handler "${kind}". Expected tenant file "${expectedPath}" exporting "${expectedExport}" or a plugin contribution.`
+      );
+    }
+    throw new Error(`No runtime handler is registered for agent handler "${kind}".`);
+  }
+  return handler;
+}
+export {
+  AGENT_HANDLER_REGISTRY,
+  getTenantAgentHandlerModulePath,
+  listRegisteredAgentHandlers,
+  loadTenantAgentHandlerRegistry,
+  resolveAgentHandler
+};

package/dist/components/DevWatchReload.astro

@@ -0,0 +1,45 @@
+---
+const enabled = import.meta.env.TREESEED_PUBLIC_DEV_WATCH_RELOAD;
+---
+
+{
+	enabled && (
+		<script is:inline>
+			(() => {
+				const endpoint = '/__treeseed/dev-reload.json';
+				let currentBuildId = null;
+
+				async function poll() {
+					try {
+						const response = await fetch(`${endpoint}?t=${Date.now()}`, {
+							cache: 'no-store',
+							credentials: 'same-origin',
+						});
+						if (!response.ok) {
+							return;
+						}
+
+						const payload = await response.json();
+						if (!payload || typeof payload.buildId !== 'string') {
+							return;
+						}
+
+						if (!currentBuildId) {
+							currentBuildId = payload.buildId;
+							return;
+						}
+
+						if (payload.buildId !== currentBuildId) {
+							window.location.reload();
+						}
+					} catch {
+						// Ignore transient polling failures while the local worker rebuilds.
+					}
+				}
+
+				poll();
+				window.setInterval(poll, 1200);
+			})();
+		</script>
+	)
+}

package/dist/components/SiteTitle.astro

@@ -0,0 +1,51 @@
+---
+import { SITE } from '../utils/seo';
+
+const { siteTitleHref } = Astro.locals.starlightRoute;
+---
+
+<a href={siteTitleHref} class="site-header-custom sl-flex" aria-label={SITE.name}>
+	<img src={SITE.logo.src} alt={SITE.logo.alt} class="site-header-logo" />
+	<span class="site-header-copy">
+		<span class="site-header-name" translate="no">{SITE.name}</span>
+		<span class="site-header-statement">{SITE.statement}</span>
+	</span>
+</a>
+
+<style>
+	@layer starlight.core {
+		.site-header-custom {
+			align-items: center;
+			gap: 0.85rem;
+			color: var(--sl-color-white);
+			text-decoration: none;
+			min-width: 0;
+		}
+
+		.site-header-logo {
+			width: 2.5rem;
+			height: 2.5rem;
+			object-fit: contain;
+			flex: 0 0 auto;
+		}
+
+		.site-header-copy {
+			display: grid;
+			min-width: 0;
+		}
+
+		.site-header-name {
+			font-size: var(--sl-text-h4);
+			font-weight: 600;
+			line-height: 1.1;
+		}
+
+		.site-header-statement {
+			font-size: var(--sl-text-xs);
+			color: var(--sl-color-gray-3);
+			white-space: nowrap;
+			overflow: hidden;
+			text-overflow: ellipsis;
+		}
+	}
+</style>

package/dist/components/content/ContentStatusLegend.astro

@@ -0,0 +1,18 @@
+---
+import { CONTENT_STATUSES, CONTENT_STATUS_META } from '../../utils/content-status';
+---
+
+<section class="border-t border-[color:var(--site-border-strong)] pt-8">
+	<p class="text-sm font-semibold uppercase tracking-[0.18em] text-[color:var(--site-accent-strong)]">Content status legend</p>
+	<div class="mt-5 grid gap-3 md:grid-cols-2 xl:grid-cols-5">
+		{CONTENT_STATUSES.map((status) => {
+			const meta = CONTENT_STATUS_META[status];
+			return (
+				<div class:list={['border-l-4 bg-[color:var(--site-bg-soft)] px-4 py-4', meta.tone]}>
+					<p class="font-semibold">{meta.label}</p>
+					<p class="mt-2 text-sm leading-7 text-[color:var(--site-text-muted)]">{meta.description}</p>
+				</div>
+			);
+		})}
+	</div>
+</section>

package/dist/components/content/StatusBadge.astro

@@ -0,0 +1,11 @@
+---
+import type { ContentStatus } from '../../utils/content-status';
+import { CONTENT_STATUS_META } from '../../utils/content-status';
+
+const { status } = Astro.props as { status: ContentStatus };
+const meta = CONTENT_STATUS_META[status];
+---
+
+<span class:list={['inline-flex items-center rounded-sm border px-3 py-1 text-[0.72rem] font-bold uppercase tracking-[0.18em]', meta.tone]}>
+	{meta.label}
+</span>

package/dist/components/docs/BookFontControls.astro

@@ -0,0 +1,180 @@
+---
+import { getBookForPath } from '../../utils/starlight-nav';
+
+const isBookPage = Boolean(getBookForPath(Astro.url.pathname));
+---
+
+{
+	isBookPage && (
+		<div class="book-font-controls print:hidden" data-book-font-controls>
+			<div class="book-font-controls__buttons" role="group" aria-label="Book text size">
+				<button
+					type="button"
+					class="book-font-controls__button"
+					data-book-font-action="decrease"
+					data-book-font-tooltip="Text size"
+					aria-label="Decrease book text size"
+				>
+					-
+				</button>
+				<button
+					type="button"
+					class="book-font-controls__button"
+					data-book-font-action="increase"
+					data-book-font-tooltip="Text size"
+					aria-label="Increase book text size"
+				>
+					+
+				</button>
+			</div>
+		</div>
+	)
+}
+
+<script is:inline>
+	const storageKey = 'docs.book-font-scale';
+	const cssVariableName = '--docs-book-font-scale';
+	const defaultScale = 1;
+	const step = 0.1;
+	const minScale = 0.85;
+	const maxScale = 1.35;
+
+	const clampScale = (value) => Math.min(maxScale, Math.max(minScale, value));
+
+	const readScale = () => {
+		try {
+			const rawValue = localStorage.getItem(storageKey);
+			const parsedValue = rawValue === null ? defaultScale : Number(rawValue);
+			return Number.isFinite(parsedValue) ? clampScale(parsedValue) : defaultScale;
+		} catch {
+			return defaultScale;
+		}
+	};
+
+	const writeScale = (value) => {
+		try {
+			localStorage.setItem(storageKey, String(value));
+		} catch {
+			// Ignore storage failures and keep the reader controls functional.
+		}
+	};
+
+	const updateButtons = (controls, value) => {
+		const decreaseButton = controls.querySelector('[data-book-font-action="decrease"]');
+		const increaseButton = controls.querySelector('[data-book-font-action="increase"]');
+
+		if (decreaseButton instanceof HTMLButtonElement) {
+			decreaseButton.disabled = value <= minScale;
+		}
+
+		if (increaseButton instanceof HTMLButtonElement) {
+			increaseButton.disabled = value >= maxScale;
+		}
+	};
+
+	const applyScale = (controls, value) => {
+		const normalizedValue = clampScale(value);
+		document.documentElement.style.setProperty(cssVariableName, String(normalizedValue));
+		updateButtons(controls, normalizedValue);
+		return normalizedValue;
+	};
+
+	const bindControls = () => {
+		for (const controls of document.querySelectorAll('[data-book-font-controls]')) {
+			if (!(controls instanceof HTMLElement) || controls.dataset.bookFontBound === 'true') continue;
+			controls.dataset.bookFontBound = 'true';
+
+			const currentValue = applyScale(controls, readScale());
+			controls.dataset.bookFontScale = String(currentValue);
+
+			for (const button of controls.querySelectorAll('[data-book-font-action]')) {
+				if (!(button instanceof HTMLButtonElement)) continue;
+				button.addEventListener('click', () => {
+					const direction = button.dataset.bookFontAction === 'decrease' ? -1 : 1;
+					const nextValue = applyScale(controls, readScale() + direction * step);
+					writeScale(nextValue);
+					controls.dataset.bookFontScale = String(nextValue);
+				});
+			}
+		}
+	};
+
+	bindControls();
+	document.addEventListener('astro:page-load', bindControls);
+</script>
+
+<style>
+	.book-font-controls {
+		display: inline-flex;
+		align-items: center;
+		color: var(--sl-color-text);
+	}
+
+	.book-font-controls__buttons {
+		display: inline-flex;
+		align-items: center;
+		border: 1px solid var(--site-border-strong);
+		border-radius: 999px;
+		background: color-mix(in srgb, var(--site-bg-elevated) 78%, white 22%);
+	}
+
+	.book-font-controls__button {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		width: 2rem;
+		height: 2rem;
+		border: 0;
+		background: transparent;
+		color: var(--site-text);
+		font-size: 1rem;
+		font-weight: 700;
+		line-height: 1;
+		cursor: pointer;
+		position: relative;
+	}
+
+	.book-font-controls__button + .book-font-controls__button {
+		border-inline-start: 1px solid var(--site-border-strong);
+	}
+
+	.book-font-controls__button:hover,
+	.book-font-controls__button:focus-visible {
+		background: color-mix(in srgb, var(--site-blue-soft) 66%, white 34%);
+		color: var(--site-blue-strong);
+	}
+
+	.book-font-controls__button::after {
+		content: attr(data-book-font-tooltip);
+		position: absolute;
+		inset-inline-start: 50%;
+		inset-block-start: calc(100% + 0.45rem);
+		transform: translateX(-50%) translateY(-0.2rem);
+		padding: 0.3rem 0.5rem;
+		border: 1px solid var(--site-border-strong);
+		border-radius: 0.45rem;
+		background: color-mix(in srgb, var(--site-bg-elevated) 88%, white 12%);
+		color: var(--site-text);
+		font-size: 0.76rem;
+		font-weight: 700;
+		letter-spacing: 0.04em;
+		text-transform: uppercase;
+		white-space: nowrap;
+		opacity: 0;
+		pointer-events: none;
+		transition:
+			opacity 140ms ease,
+			transform 140ms ease;
+	}
+
+	.book-font-controls__button:hover::after,
+	.book-font-controls__button:focus-visible::after {
+		opacity: 1;
+		transform: translateX(-50%) translateY(0);
+	}
+
+	.book-font-controls__button:disabled {
+		opacity: 0.45;
+		cursor: not-allowed;
+	}
+</style>

package/dist/components/docs/DesktopSidebarToggle.astro

@@ -0,0 +1,88 @@
+---
+interface Props {
+	side: 'left' | 'right';
+	label: string;
+}
+
+const { side, label } = Astro.props;
+
+const sidebarId = side === 'left' ? 'starlight__sidebar' : 'starlight__page-toc';
+const iconPath =
+	side === 'left'
+		? 'M15.75 19.5 8.25 12l7.5-7.5'
+		: 'M8.25 4.5 15.75 12l-7.5 7.5';
+---
+
+<button
+	type="button"
+	class="desktop-sidebar-toggle"
+	data-docs-sidebar-toggle={side}
+	data-label={label}
+	aria-controls={sidebarId}
+	aria-expanded="false"
+>
+	<span class="desktop-sidebar-toggle__icon" aria-hidden="true">
+		<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+			<path d={iconPath} />
+		</svg>
+	</span>
+	<span class="desktop-sidebar-toggle__text">{label}</span>
+</button>
+
+<style>
+	@layer starlight.components {
+		.desktop-sidebar-toggle {
+			display: none;
+		}
+
+		@media (min-width: 72rem) {
+			.desktop-sidebar-toggle {
+				display: inline-flex;
+				align-items: center;
+				gap: 0.45rem;
+				border: 1px solid var(--sl-color-hairline);
+				border-radius: 999px;
+				padding: 0.45rem 0.8rem;
+				background: color-mix(in srgb, var(--site-bg-soft) 84%, white 16%);
+				color: var(--site-text-muted);
+				font-size: 0.85rem;
+				line-height: 1;
+				transition:
+					background-color 160ms ease,
+					border-color 160ms ease,
+					color 160ms ease;
+			}
+
+			.desktop-sidebar-toggle:hover,
+			.desktop-sidebar-toggle:focus-visible {
+				background: color-mix(in srgb, var(--site-blue-soft) 52%, white 48%);
+				border-color: var(--site-blue);
+				color: var(--site-text);
+			}
+
+			.desktop-sidebar-toggle[aria-expanded='true'] {
+				background: color-mix(in srgb, var(--site-blue-soft) 68%, white 32%);
+				border-color: var(--site-blue);
+				color: var(--site-text);
+			}
+
+			.desktop-sidebar-toggle__icon {
+				display: inline-flex;
+				align-items: center;
+				justify-content: center;
+				width: 1rem;
+				height: 1rem;
+			}
+
+			.desktop-sidebar-toggle__icon svg {
+				width: 1rem;
+				height: 1rem;
+				fill: none;
+				stroke: currentColor;
+				stroke-width: 1.8;
+				stroke-linecap: round;
+				stroke-linejoin: round;
+			}
+		}
+	}
+</style>

package/dist/components/docs/DownloadBook.astro

@@ -0,0 +1,34 @@
+---
+import { getDocsDownloadForPath } from '../../utils/starlight-nav';
+
+const download = getDocsDownloadForPath(Astro.url.pathname);
+---
+
+{
+	download && (
+		<a
+			href={download.downloadHref}
+			download={download.downloadFileName}
+			aria-label={download.downloadTitle}
+			class="download-button docs-download-button print:hidden"
+		>
+			<svg
+				xmlns="http://www.w3.org/2000/svg"
+				width="16"
+				height="16"
+				viewBox="0 0 24 24"
+				fill="none"
+				stroke="currentColor"
+				stroke-width="2"
+				stroke-linecap="round"
+				stroke-linejoin="round"
+				aria-hidden="true"
+			>
+				<path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
+				<polyline points="7 10 12 15 17 10" />
+				<line x1="12" x2="12" y1="15" y2="3" />
+			</svg>
+			<span>Download Book</span>
+		</a>
+	)
+}