create-ternent-app

Scaffold replay-first Ternent applications with a tiered template matrix:

• Core Only: raw TypeScript infrastructure over @ternent/concord and @ternent/ledger
• Functional Blueprint: a vanilla HTML/TS sandbox that logs replay state in real time
• App Shell: a richer app-runtime shell with native system modules, privacy services, and framework overlays
• Integrate Existing: an additive Ternent integration subtree for existing host applications

Install

Published create-flow target:

npm create @ternent/ternent-app@latest

Equivalent direct binary usage after install:

pnpm dlx @ternent/create-ternent-app

The CLI opens an interactive prompt wizard and generates a new project in the current directory.

Runtime requirements:

• Node.js >=20
• pnpm 11.x for local development and release verification

Scaffolding Matrix

1. Core Only

Use this when you want the smallest possible footprint.

Generated shape:

• raw TypeScript project
• createConcordApp wiring
• replay plugin examples
• ternent.config.ts with feature calibration
• no framework code

Best for:

• infrastructure prototypes
• library-style runtimes
• custom host applications that want to own UI and storage themselves

2. Functional Blueprint

Use this when you want a simple browser-visible sandbox without committing to React, Vue, or Svelte.

Generated shape:

• vanilla index.html
• plain TypeScript entrypoint
• live replay-state logging
• basic task plugin example
• no framework overlay config

Best for:

• demos
• teaching
• event-log and replay debugging
• validating command and projection behavior quickly

3. App Shell

Use this when you want the higher-level workspace-style runtime pattern.

Generated shape:

• createAppApi-style host layer
• runtime privacy service
• audience-aware task plugin
• framework overlay for react, vue, or svelte
• mnemonic onboarding UI surface
• useTernent bridge hook/composable/helper in the selected framework

Best for:

• product-facing apps
• identity-led onboarding flows
• privacy-aware collaborative workspaces
• apps that want to start close to the Ternent workspace runtime model

Scope note:

• this is an advanced scaffold, not a full clone of the ../workspace product runtime
• identity, onboarding, storage, and privacy flows are scaffold seams intended for extension

4. Integrate Existing

Use this when you already have an application shell and want to add Ternent without replacing your host architecture.

Generated shape:

• root ternent.config.ts
• src/ternent/ integration subtree
• native users and permissions system seams
• identity-session and privacy runtime services
• framework adapter and mountable integration panel
• sample plugin and viewer-filtered selectors

Mutation modes:

• safe-report-only: generates a root integration report and leaves package.json untouched
• assisted-package-json: updates package.json with Ternent dependencies and a namespaced check script

Best for:

• existing frontend products
• teams with an established router and design system
• incremental Ternent adoption inside a live codebase

Prompt Flow

The CLI currently routes through these decisions:

1. Project Name
2. Core Layer Profile
3. Frontend Framework UI for App Shell only
4. Host Framework for Integrate Existing
5. Target Source Root for Integrate Existing
6. Host Integration Style for Integrate Existing
7. Package Mutation Mode for Integrate Existing
8. Default Core Components for every tier except Core Only

Default feature toggles:

• System Users & Identity
• System Permissions & Audience Privacy
• Snapshot Engine & Local Ledger Cache

Those selections are injected into generated config so template placeholders are replaced during scaffold.

Routing notes:

• Core Only skips framework and feature prompts entirely
• Functional Blueprint skips framework selection but still captures feature toggles
• App Shell requires a framework overlay
• Integrate Existing captures framework, source root, integration style, and package mutation mode before feature selection

Pluggable Sync Lifecycle Hooks

The generated projects are structured around a strict separation:

• local replay runtime
• pluggable remote synchronization boundary

At the configuration layer, the intended hook shape is:

export const ternentEngine = createEngine({
  systemModules: {
    users: true,
    permissions: true,
  },
  features: {
    ageEncryption: true,
  },
  syncStrategy: {
    onPush: async (localCommits) => {
      // send signed commits to a remote relay, pod, object store, or API
    },
    onPull: async () => {
      // fetch remote commits or snapshots and return them to the local runtime
    },
    resolveConflict: (local, remote) => {
      // choose merge policy explicitly
      return local;
    },
  },
});

This boundary is intentionally pluggable. The central system should be treated as transport and persistence, not as the source of truth. Replayable signed history remains authoritative.

Typical sync targets:

• HTTP relay
• object storage
• Solid Pod
• custom file-based import/export
• CRDT or collaboration layer mounted above or beside Concord

Template Inventory

Repo inventory lives under templates/:

• templates/core-only/base/
• templates/functional-blueprint/base/
• templates/app-shell/base/
• templates/app-shell/react/
• templates/app-shell/vue/
• templates/app-shell/svelte/
• templates/integrate-existing/base-root/
• templates/integrate-existing/isolated-module/
• templates/integrate-existing/plugin-api-seams-only/
• templates/integrate-existing/react/
• templates/integrate-existing/vue/
• templates/integrate-existing/svelte/

The scaffold engine copies the appropriate base template, applies any framework overlay, and replaces template variables such as:

• __PROJECT_NAME__
• __FEATURE_IDENTITY__
• __FEATURE_PERMISSIONS__
• __FEATURE_AGE_ENCRYPTION__

Local Development

Install dependencies:

pnpm install

Run the verification suite:

pnpm run verify

Build the published CLI payload:

pnpm build

Repository Status

Current verified coverage includes:

• prompt routing
• Clack adapter behavior
• recursive scaffold copy engine
• template variable injection
• config calibration
• compiled binary smoke test against the real template inventory