@ysh/web-setup

@n-tco/ysh-web-setup

Local web UI to read and write a YSH client config/ folder — the four JSON config files (data-structure, page-structure, role-structure, track-and-trace) plus the directory assets (logic/, role/, page/, task/, report/). Every save is validated against the config schema and cross-reference rules that mirror the Java ysh-setup module, so the JSON you edit here is exactly what ysh-setup will provision.

It runs entirely on your machine: a tiny Node file-API server reads/writes the files, and a React UI (built and bundled) talks to it. Nothing leaves your laptop.

Usage (in a client folder)

From a client directory that contains a config/ folder (e.g. sno-paris-make):

cd sno-paris-make
npx @n-tco/ysh-web-setup

Then open the printed URL (default http://localhost:4599). The tool auto-detects the client id from config/data-structure.{CLIENT}.json and lets you edit everything in config/.

You can also add it as a dev dependency and a script:

npm install --save-dev @n-tco/ysh-web-setup

// package.json
{
  "scripts": {
    "config": "ysh-web-setup"
  }
}

npm run config

Options

• --dir <path> / env YSH_WEB_SETUP_CONFIG_DIR — point at a specific config directory (default: ./config under the current directory).
• env YSH_WEB_SETUP_PORT — server port (default 4599).

What you can edit

JSON config (structured editors, validated on save):

| File | Editor | |------|--------| | data-structure.{CLIENT}.json | Documents → fields, content lines, references (dropdown of other domains), grants, document type, navigation, transaction-auth roles | | page-structure.{CLIENT}.json | Navigation pages (section/group, name, page) | | role-structure.{CLIENT}.json | Roles → entities with a named-boolean grant matrix (global/list/view/print/dashboard/create/edit) + users | | track-and-trace.{CLIENT}.json | Workflows → trace rows |

Directory assets (browse / create / edit / delete):

| Dir | Naming convention | |-----|-------------------| | logic/ | {DOMAIN}.{command}.js | | role/ | {DOMAIN}.js | | page/ | {path}.html / {path}.js | | task/ | {taskCode}/{command}.js | | report/ | {DOMAIN}/{key}.jrxml |

Validation

Saving is blocked while any error exists (warnings are allowed). Checks mirror ysh-setup:

• Required fields (domainId, field, dataType, lineId, role/user ids…).
• navigation must be section/group.
• Unique domainId; REFERENCE/REFERENCE_LIST fields must point to a domain declared in the same data-structure (the JS equivalent of findDocumentNotFound); COMPONENT needs a class.
• role-structure requires at least one user (matching createDocumentRole).

Saved JSON is pretty-printed (2-space indent, trailing newline) so git diffs stay clean.

How it fits the deploy flow

ysh-setup reads JSON (not Excel). Deploy copies only config/*.json (and the asset dirs) into metadata. Use this tool to author/maintain the JSON; use the excel-to-json converter (YSH.Script/tools/excel-to-json) only for the one-time migration from legacy .xlsx.

Developing this package

npm install
npm run dev     # starts the file-API server + Vite (proxied) with hot reload
npm run build   # builds the UI into dist/
npm start       # serves the built UI + file-API from dist/

Set YSH_WEB_SETUP_CONFIG_DIR to test against a real client config while developing.

Publishing (public npm)

npm login
npm version patch        # or minor / major
npm publish              # publishConfig.access=public is set in package.json

The published tarball contains server/, shared/, and the built dist/ (the UI source and Vite config are excluded via .npmignore), so consumers get a ready-to-run tool via npx @ysh/web-setup.

Architecture

See ARCHITECTURE.md.