@treeseed/core

@treeseed/core is the Treeseed integrated platform starter for Astro/Starlight sites, Hono API runtimes, agent runtimes, and worker services. It contains the published web runtime, API runtime, manager/worker entrypoints, integrated local dev orchestration, shared components and styles, the knowledge-factory content model, and the forms stack used by Treeseed tenants.

This repository is the package root. Run package commands from core, not from the top-level treeseed workspace.

Requirements

• Node >=22
• npm >=10

Install

For package contributors:

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:

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 shared working-site fixture in treeseed-fixtures.

Shared Fixture Usage

@treeseed/core validates itself against the integrated shared fixture, not a Core-specific fork.

That means the fixture may reference package surfaces owned by sdk, core, and cli, and isolated Core verification links the real local core package into the shared fixture instead of maintaining a separate agent package boundary.

Commands

Core development

npm run dev
npm run dev:web
npm run dev:api
npm run dev:worker
npm run dev:workday-start
npm run dev:workday-report
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:

• dev: starts the integrated Astro UI and Hono API local runtime from core
• dev:web: starts only the Astro UI dev surface through the core runtime
• dev:api: starts only the Hono API dev surface through the core runtime
• dev:worker, dev:workday-start, dev:workday-report: start the worker-service entrypoints from core
• 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

npm run verify
npm run verify:local
npm run verify:action

npm run verify uses the shared Treeseed SDK verify driver in auto mode.

• npm run verify auto-selects between local direct verification and the gh act workflow path
• npm run verify:local forces local direct verification against the current repo state
• npm run verify:action forces the isolated workflow path through gh act
• npm run verify:direct is the raw package verification chain used by the driver

The direct 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

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
• release:publish publishes the package to npm

GitHub Actions

This repo ships two package workflows:

• ci.yml: runs on push and pull request, installs with npm ci, then runs npm run verify
• 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 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 exports.

The published package includes:

• dist/
• tsconfigs/
• templates/
• style/
• utils/
• README.md

The package currently depends on @treeseed/sdk plus the runtime packages needed for its web, API, and worker surfaces. It does not depend on @treeseed/cli.

Contributor Workflow

Typical local workflow:

npm install
npm run verify

If you only need one stage:

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.
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.