Skip to content

README.md

Latest commit

 

History

History
127 lines (94 loc) · 4.33 KB

README.md

File metadata and controls

127 lines (94 loc) · 4.33 KB
Raw

@ui-engine/cli

Single entry point for the ui-engine workspace tooling. Exposes a ui-engine bin that dispatches to the per-package CLIs (@ui-engine/knowledge, @ui-engine/prompts), wraps the standalone slicer scripts, and adds the widgets scaffold generator that ties widget source, README entries, and knowledge records together.

Install

This package is part of the ui-engine workspace. After npm install at the repo root, the bin is available as npx ui-engine. The root package.json scripts (knowledge:check, prompts:lint, assets:inspect, ...) all wrap ui-engine <namespace> <subcommand>.

Command reference

ui-engine <namespace> <subcommand> [options]

Namespaces:
  knowledge   Records, playbooks, skill drafts, and semantic retrieval.
  prompts     Per-asset prompt registry, lineage manifests, and validation.
  assets      Inspect and slice generated HUD asset packs.
  widgets     Scaffold new widgets across @ui-engine/* packages.
  help        Print top-level help (alias: --help, -h).

ui-engine knowledge ...

Delegates to @ui-engine/knowledge's ui-engine-knowledge CLI.

ui-engine knowledge check
ui-engine knowledge new <slug>
ui-engine knowledge index
ui-engine knowledge retrieve "<query>" [--top-k N] [--types record,playbook,skill]
ui-engine knowledge export-skills [--out-dir <dir>]
ui-engine knowledge capture [--from-conversation <file>]

capture is intentionally a polished placeholder until the implementation lands; it explains what the future version will do and exits 0.

ui-engine prompts ...

Delegates to @ui-engine/prompts's ui-engine-prompts CLI.

ui-engine prompts new <asset-type> <slug>
ui-engine prompts lint
ui-engine prompts lineage <asset-or-glob>

ui-engine assets ...

Wraps the standalone scripts under scripts/hud-assets/.

ui-engine assets inspect [--assets-dir <dir>] [--json]
ui-engine assets slice <pack>
# <pack> = banner | cards | icons | route | dividers | emblem | all

assets slice all chains the slicers in the order banner → cards → icons → route → dividers → emblem and stops on the first non-zero exit.

ui-engine widgets ...

ui-engine widgets scaffold <Name> --in <package-slug>

Generates three artifacts in one command:

  1. packages/<package-slug>/src/<Name>.ts — widget source stub extending Widget from @ui-engine/core. Errors if the file already exists.
  2. packages/knowledge/records/kg-<YYYYMMDD>-<name-kebab>-stub.md — record stub with the M2 schema (frontmatter + the six required sections, all marked TODO). Errors if a record with that id already exists.
  3. An updated row in packages/<package-slug>/README.md widgets table. The table is created the first time and appended to thereafter; the marker <!-- widgets:scaffolded --> identifies it for future appends.

After scaffolding, the command runs ui-engine knowledge check as a smoke test so a malformed stub is caught immediately.

Validation errors:

  • <Name> must match ^[A-Z][A-Za-z0-9]*$ (PascalCase).
  • <package-slug> must reference an existing packages/<slug>/ directory.
  • The widget source file must not already exist.
  • The record file for today must not already exist (suggests a different name).

Programmatic API

Only the side-effect-free helpers are surfaced through @ui-engine/cli:

import { scaffoldWidget, toKebabCase } from '@ui-engine/cli';

const result = await scaffoldWidget({
  name: 'UnitPortrait',
  packageSlug: 'primitives',
});
console.log(result.widgetFile, result.recordFile, result.readmeFile);

The dispatcher itself (runDispatcher) is intentionally not exported; it calls process.exit and is wired to the bin entry only.

How delegation works

knowledge and prompts subcommands spawn the underlying compiled CLIs (packages/knowledge/dist/cli/index.js, packages/prompts/dist/cli/index.js) as child processes with stdio: 'inherit'. Exit codes and signals are forwarded faithfully. This keeps the wrappers minimal and avoids any re-implementation drift.

assets subcommands likewise spawn the existing scripts/hud-assets/*.mjs files; they're already standalone Node scripts.

widgets scaffold is implemented in this package because it produces files across multiple packages (source, knowledge, README) and ties them together with a follow-up validation pass.