@prata.ma/anvil-hub

Remote collaboration runtime and CLI for Anvil workspaces.

Overview

@prata.ma/anvil-hub owns the package-level runtime behind Anvil's Hub model. It provides adapter contracts for Document, Memory, and Session, a current Notion-backed document implementation, config-driven sync over local @product/, @system/, and @state/ roots, and a standalone hub CLI surface.

Within the workspace, this package stays reusable by accepting config objects and source context directly. @prata.ma/anvil composes it into the broader Anvil CLI, while @prata.ma/anvil-hub owns the runtime behavior itself.

Installation

Install from npm or consume it through a workspace dependency while developing inside this monorepo.

npm

pnpm add @prata.ma/anvil-hub

Workspace

{
  "dependencies": {
    "@prata.ma/anvil-hub": "workspace:*"
  }
}

Usage

@prata.ma/anvil-hub supports both library-style usage and the packaged hub CLI.

Library

import {
  createHub,
  createHubSyncEngine,
  getDocumentAdapter,
  getResolvedHubConfig,
} from '@prata.ma/anvil-hub'

const runtime = createHub({
  baseDir: process.cwd(),
  config: {
    document: { provider: 'notion', rootId: 'root-page-id' },
    sync: { product: '@product', state: '@state', system: '@system' },
  },
  sourceContext: {
    device: 'laptop',
    workspace: 'anvil',
    zone: 'main',
  },
})

const config = getResolvedHubConfig(runtime)
const document = getDocumentAdapter(runtime)
const engine = createHubSyncEngine(runtime, document, {
  productRoot: config.sync.product,
  rootPageId: runtime.config.document?.rootId ?? '',
  stateRoot: config.sync.state,
  systemRoot: config.sync.system,
})

await engine.syncProduct()

CLI

hub status --config hub.json --workspace anvil
hub sync --config hub.json --workspace anvil --product --system
hub query --config hub.json --workspace anvil "recent decisions"
hub pull --config hub.json --workspace anvil

Patterns

Common package flows include:

• creating a runtime from a caller-owned HubConfig and SourceContext
• resolving sync roots relative to a runtime base directory
• using the standalone hub CLI against an explicit JSON config file
• syncing product, system, and state roots through the shared HubSyncEngine

API

@prata.ma/anvil-hub exposes a library surface plus dedicated CLI entrypoints.

Exports

• @prata.ma/anvil-hub - root library surface
• @prata.ma/anvil-hub/cli - CLI module entrypoint
• runtime helpers such as createHub, getHubStatus, getResolvedHubConfig, getDocumentAdapter, getMemoryAdapter, getSessionAdapter, and createHubSyncEngine
• standalone command runners runHubPullCommand, runHubQueryCommand, runHubStatusCommand, and runHubSyncCommand
• package types including HubConfig, HubRuntime, HubStatus, SourceContext, SyncOptions, SyncResult, SessionSummary, and adapter-facing result types

Commands

The package ships one binary:

• hub - standalone Hub CLI entrypoint

Top-level command areas currently include pull, query, status, and sync.

Status And Query

hub status --config hub.json --workspace anvil
hub query --config hub.json --workspace anvil "roadmap"

Sync And Pull

hub sync --config hub.json --workspace anvil --product
hub sync --config hub.json --workspace anvil --system --state
hub pull --config hub.json --workspace anvil

Configuration

• HubConfig is the primary runtime contract for the package.
• getResolvedHubConfig() returns the effective config and defaults sync roots to @product, @state, and @system relative to the runtime base directory.
• The CLI requires an explicit config file path and builds SourceContext from workspace, optional device, and optional zone.

Development

Use the package-local scripts while working in @packages/anvil-hub, and keep real runtime behavior in importable modules rather than in the CLI wrappers.

Commands

pnpm --filter @prata.ma/anvil-hub release:check
pnpm --filter @prata.ma/anvil-hub build
pnpm --filter @prata.ma/anvil-hub lint
pnpm --filter @prata.ma/anvil-hub test
pnpm --filter @prata.ma/anvil-hub test:type

Testing

The current package tests focus on the scaffold smoke path and config-root resolution.

Conventions

• Keep CLI commands thin and route behavior through package-owned runtime modules.
• Keep local repo artifacts as source of truth; Hub mirrors outward from local state.
• Keep @prata.ma/anvil-hub config-driven and avoid loading anvil.yaml as the primary runtime contract.

Status

This package is active and currently focused on the remote collaboration runtime layer for Anvil workspaces.

Maturity

@prata.ma/anvil-hub is active and publish-prepared.

Scope

The package currently supports a real Notion Document adapter, stub Memory and Session adapters, config-driven runtime creation, a standalone hub CLI, and sync modules for product, system, and state roots. Product and system sync remain the current validated surfaces, while state sync remains a more careful follow-up area.

Notes

• @prata.ma/anvil-hub now participates in the repo's Changesets, npm publish, and GitHub Release automation.
• @prata.ma/anvil composes Hub into the main Anvil CLI, but @prata.ma/anvil-hub should remain reusable as a standalone runtime package.
• Real Supermemory and OpenSync integrations are still deferred behind the existing adapter interfaces.