@forgeax/toolkit

Independent ForgeaX extension contracts, Local Runner, artifact compiler, and external-target Builder toolkit.

Architecture

src/
├── cli/      # command parsing and routing
├── runner/   # public contracts plus the target-neutral Local Host
└── builder/  # native artifacts and external BuilderPlugin targets

Toolkit has no dependency on another @forgeax/* package. It publishes the native extension standard from @forgeax/toolkit/contracts; Local Runner and ForgeaX Studio load the same compiled extension module.

Create an extension

forgeax-toolkit create my-extension
cd my-extension
npm install

The generated business package contains one explicit public manifest and one Extension.apply(ctx, config) source module. It contains no host page, React root, Studio entry, transport, composition patch, or target runtime dependency.

Native ForgeaX Hosts

forgeax-toolkit dev local
forgeax-toolkit dev forgeax-studio-base
forgeax-toolkit package local
forgeax-toolkit package forgeax-studio-base

local and forgeax-studio-base are native targets, not BuilderPlugins. Both compile the same target-neutral artifact under .forgeax/<dev|build>/native:

package.json                 # forgeaxExtension metadata
forgeax-extension.json       # unchanged public manifest
dist/extension.js            # single lifecycle module
assets/                      # optional static assets

Local development starts the Toolkit-owned Host shell. Studio development starts the same module server and writes a versioned registration containing artifactDirectory, manifestPath, moduleUrl, ownership, PID, heartbeat, and exact allowed origin. Studio owns its Host Adapter and lifecycle.

External targets

forgeax-toolkit dev deepseek-harness --profile <name>
forgeax-toolkit package deepseek-harness
forgeax-toolkit dev <target> --plugin <module>

DeepSeek Harness and third-party platforms remain BuilderPlugin targets. --plugin may explicitly override any target for debugging. Generated target files stay outside extension business source and are written only through the bounded context.writeFile() API.

Use --generate-only to inspect generated development material without starting a process.

Public APIs

Manifest, package, registration, and lifecycle interfaces:

import type { Extension, ExtensionContext } from '@forgeax/toolkit/contracts';

Local Host and React View implementation:

import { StandaloneExtensionHost } from '@forgeax/toolkit/runner';

Every resource must be registered through ctx.effect(). Local Runner and Studio Host must provide reverse-order cleanup, activation rollback, reload, and deactivation with the same contract semantics.