Internal setup — local development for SDK contributors

This document is for contributors to the SDK itself. If you only consume @asteby/metacore-* packages from another app, see consumer-guide.md instead.

Table of contents

• Prerequisites
• Clone and install
• Repository layout
• Common workflows
• Linking against a consumer app
• GOPRIVATE setup
• CI secrets

Prerequisites

• Node.js 20+ and pnpm 10+ (the root packageManager field is authoritative; corepack enable will install the matching pnpm).
• Go 1.22+ for the CLI (cli/) and Go helpers (pkg/).
• TinyGo 0.31+ only if you rebuild the WASM examples.
• GitHub PAT with repo (read) scope only if you also work against any private Go modules in your fork — see GOPRIVATE setup.

Clone and install

git clone https://github.com/asteby/metacore-sdk.git
cd metacore-sdk

# Go side — CLI, pkg/ helpers, examples/
go mod download
go test ./...

# npm side — packages/* monorepo
corepack enable
pnpm install
pnpm -r build
pnpm -r test

Repository layout

metacore-sdk/
├── cli/          # Go CLI — init, validate, build, sign, compile-wasm
├── pkg/          # Go SDK helpers — manifest types, signing, host context
├── packages/     # pnpm workspace — @asteby/metacore-* npm packages
├── examples/     # reference addons (built in CI to catch regressions)
├── templates/    # scaffold templates embedded by the CLI
├── docs/         # public documentation
└── .changeset/   # version + changelog state (see PUBLISHING.md)

Common workflows

# Build everything
pnpm -r build

# Build a single package and watch
pnpm --filter @asteby/metacore-ui dev

# Type-check
pnpm typecheck

# Lint
pnpm lint

# Test
pnpm test

# Generate TypeScript types from Go (tygo)
pnpm codegen

# Author a changeset (any PR that touches packages/* needs one)
pnpm changeset

For Go:

go test ./...
go build -o bin/metacore ./cli
./bin/metacore help

Linking against a consumer app

When iterating on a package in tandem with a consumer host application, use a file: reference from the consumer to this repo. See consumer-guide.md § Mixed npm + file: pattern.

Build the package whenever you change it — pnpm symlinks the dist/, so the consumer picks up the new bundle on its next dev-server restart (or HMR for ESM):

pnpm --filter @asteby/metacore-runtime-react build

GOPRIVATE setup

The Metacore kernel and SDK are both public, so you only need this if your fork or downstream host application depends on a private Go module of your own. Configure Go to fetch it through your PAT:

export GOPRIVATE=github.com/your-org/your-private-module

cat >> ~/.netrc <<EOF
machine github.com
  login <your_github_user>
  password <PAT_with_repo_read>
EOF
chmod 600 ~/.netrc

The PAT must have repo (read) scope for the private repositories you list.

CI secrets

The following secrets are configured at the GitHub organization level for CI to publish:

• NPM_TOKEN — npm publish token for @asteby scope (Granular Access Token with "Bypass 2FA" enabled — see publishing.md).
• GHCR_TOKEN — token with write:packages scope for ghcr.io.