@roya-ai/royascaff

A web-portal-driven compiler for software architecture — a code-independent, multi-app, multi-target plan graph that an AI compiler materializes into real code.

Install globally

npm i -g @roya-ai/royascaff

Or run without installing:

npx @roya-ai/royascaff init

Quick start for a new project

1. Scaffold the model folder

Run this once at the root of your project:

cd my-project
royascaff init --name my-project

This creates a .royascaff/ folder at your project root:

.royascaff/
  model/
    project/my-project.yaml   ← starter Project node
    edges.yaml                ← typed relationships (empty to start)
    apps/  modules/  features/  endpoints/  services/  ...
  targets/
    backend/rules.md          ← AI coding rules per target
    web/rules.md
    mobile/rules.md
  views/                      ← generated markdown views
  history/                    ← plan commit snapshots
  acceptance/                 ← generated acceptance checks
  README.md

2. Open the portal and fill in your model

royascaff portal --open

The portal opens at http://localhost:4000. It serves the full web UI and the REST API from the same process.

Inside the portal:

• Explorer — browse Apps → Modules → Features → Projections
• + New (AI) — describe what you want; the AI wizard generates questions and cascades a full change-set (creates App, Modules, Features, Endpoints, Services, etc.)
• Build — run code generation on a git branch via the agent CLI
• Changes — view uncommitted model diff, plan commit history, git working state
• Checks — run validation and reconcile (plan vs actual code)

3. Validate the model

royascaff validate

4. Generate markdown views

royascaff build
# → .royascaff/views/{apps,modules,features,endpoints,services,...}.md

5. Compile to graph.json (for tooling)

royascaff graph
# → .royascaff/model/graph.json

6. Reconcile plan vs code

royascaff reconcile -s ./src

7. Plan version control

royascaff plan commit -m "added auth module"
royascaff plan log
royascaff plan diff <commit-id>

All CLI commands

| Command | Description | |---------|-------------| | royascaff init [dir] | Scaffold .royascaff/ in a project directory | | royascaff portal | Launch web portal (API + bundled UI) | | royascaff validate | Validate schema, edges, completeness | | royascaff build | Render markdown views | | royascaff graph | Compile graph.json | | royascaff scan -s <dir> | Check @ac annotation drift | | royascaff lock | Write build.lock | | royascaff reconcile -s <dir> | Diff plan vs source code | | royascaff acceptance | Generate acceptance check stubs | | royascaff plan commit -m <msg> | Snapshot current model | | royascaff plan log | List snapshots | | royascaff plan diff <a> [b] | Diff two snapshots |

Portal options

royascaff portal --port 4000   # default
royascaff portal --open        # open browser automatically
royascaff portal --model <dir> # override model directory
royascaff portal --repo <dir>  # override repo root for git operations

Environment variables (portal)

| Variable | Default | Description | |----------|---------|-------------| | AI_CLI_PROVIDER | cursor | Agent CLI provider (cursor, command, mock) | | CURSOR_AGENT_MODEL | auto | Model passed to cursor-agent --model | | CURSOR_AGENT_BIN | (auto) | Path to cursor-agent binary | | PORT | 4000 | HTTP port |

Path detection

All commands auto-detect the .royascaff/ folder by walking up from the current directory. You can always override:

royascaff --model /path/to/.royascaff/model validate

Using as a library

import { loadModel, validateGraph, Graph } from '@roya-ai/royascaff';

const { graph, errors } = loadModel('/path/to/.royascaff/model');
const diagnostics = validateGraph(graph);

Development (contributing to the engine)

git clone ...
cd royascaff-engine
npm install
npm run dev:portal   # API server (port 4000) + Vite dev server (port 5173) in parallel

Publishing a new version

npm run release          # bumps patch, builds, publishes to npm
npm run release -- minor # bumps minor version

Prerequisites: npm login with access to the @roya npm organization.

Architecture

@roya-ai/royascaff/
  src/
    schema/index.ts       IR schema (Zod)
    model/                loader, graph, validate, mutate, changeset, ...
    compiler/             scaffold, build, agent CLI
    agent/                IAgentCli (Cursor, CommandTemplate, Mock)
    portal/
      server.ts           createPortalServer() Express factory
      dev.ts              dev entry point (API only, Vite serves UI)
    cli.ts                `royascaff` binary
  web/                    React + Vite source (bundled to dist/web/)
  dist/                   compiled output (shipped to npm)
    cli.js                the global binary
    index.js              library entry
    web/                  pre-built portal UI

The .royascaff/ folder lives at the project root, never inside the engine package.