mdk-create-app

Files (1)

• SKILL.md

SKILL.md (first lines)

# Create an MDK App (`mdk-create-app`)

An MDK App is a self-contained, publishable npm package that bundles a backend plugin, a UI shell module, and an `mdk-app.yaml` manifest.

This skill governs the **creation and scaffolding phase** of an MDK App before it is added to a site or published.

---

## 1. The Package Layout

Every scaffolded app follows the canonical structure:

```text
@tetherto/mdk-app-<name>@<version>
├── package.json        # name, version, files, dependencies, peerDependencies
├── mdk-app.yaml        # app manifest
├── plugin/             # backend plugin template
│   ├── mdk-plugin.json # route table (the Gateway serves it under /apps/<name> unless mounted)
│   ├── controllers/    # route handlers
│   └── lib/            # client helper used by the handlers
└── ui/                 # built UI module with index entry point
    └── index.js
```

---

## 2. The Strict `mdk-app.yaml` Specification

`mdk-app.yaml` defines the app's identity, permissions, and configuration. It contains these 5 keys, plus an optional
one-line `description`:

```yaml
id: io.tether.sentinel              # 1. Immutable identity, reverse-DNS
version: 0.1.0                     # 2. Semver; must equal package.json version
displayName: Sentinel              # 3. Shown in shell's sidebar and CLI
permissions:                       # 4. The Kernel access the app's service account needs; required ([] for none)
  - resources: [devices]
    verbs: [read]                  # Default: read (least privilege; [read, write] for controls/tuning)
    resourceNames: ["*"]           # Default: allow all devices ("*"), or scoped: family/brand/worker/device
config:                            # 5. Operational defaults (overridable in mdk.yaml)
  driftThresholdPct: 10
```

### Critical Negative Constraints: What NOT to Add
* **DO NOT add extraneous top-level keys**: Never add `icon`, `routes`, `auth`, `mcp`, `devices`, `metadata`, or `entry`. The specification limits the manifest to these 5 keys plus `description`; `mdk validate app` reports any other key.
* **`config` must always be an object**: If the app has no default configuration parameters, write `config: {}`. Never leave it null, undefined, or an array.

---

## 3. Edge Cases & Validation Rules

### Edge Case 1: Directory & Location Context
* **Standalone Repo Mode (Outside an MDK project)**: If the current directory is an empty folder or standalone repo (no `mdk.yaml` in current or parent directories), scaffold files **directly at the root of the current directory**:
  `./package.json`, `./mdk-app.yaml`, `./plugin/`, `./ui/`.
* **Site Project Mode (Inside an MDK project)**: If an `mdk.yaml` exists in the current or parent directory, scaffold under `apps/<name>/`.
* **Distinction from Dashboard Shells**: An MDK App package (`@tetherto/mdk-app-<name>`) is a backend plugin + dynamic UI shell module. It is distinct from a standalone Vite dashboard shell created via `mdk create dashboard <name>` (which defaults to `apps/dashboard`). If developing an app inside a site repo alongside an existing dashboard, ensure distinct directory names (e.g. `apps/<name>-app` or keep the dashboard at `apps/dashboard`).

### Edge Case 2: RBAC Permissions & Device Hierarchy
* **Enforced**: `mdk create app`, `mdk add app` and `mdk rbac init` write these rules as the role `app-<name>` in `spec.rbac`,
  and the Kernel refuses every call the role does not allow (`ERR_KERNEL_ACTION_FORBIDDEN`, a `403` at the Gateway). Derive the
  rules from the plugin code with the [`mdk-app-rbac`](../mdk-app-rbac/SKILL.md) skill rather than guessing them.
* **Target resources**: only the Kernel resources `devices`, `workers`, `commands`, `actions`, `policy`, `identities`, each with its
  own verbs ([`kernel-access.md`](../mdk-app-rbac/references/kernel-access.md)). The scaffold's summary route needs
  `resources: [workers]`, `verbs: [list]`. Never `[*]`, `[plugins]` or `[kernel]`.
* **Verbs**:
  * Default: `verbs: [read]` (least privilege; for monitoring, telemetry, and metrics dashboards).
  * Control / Tuning apps (reboots, parameter tuning, commands): `verbs: [read, write]`.
* **Device Scoping (`resourceNames`)**: Defaults to `["*"]` to allow all devices. When scoped, it must follow the 4-part MDK device hierarchy:
  `family / brand / worker / device`
  * `*` — All devices across all families (Default: allow all).
  * `miner/*` — All miners across all brands.
  * `miner/antminer/*` — All Antminers across all workers.
  * `miner/antminer/antminer-a/*` — Devices under worker `antminer-a`.
  * `powermeter/*` — All power meters (note: backend family identifier is `powermeter`, not `power-meter`).
  * `sensor/*`, `container/*` — Sensors and containers.
* **Multiple Device Families**: If an app needs access to multiple hardware types, declare separate scoped rule blocks:
  ```yaml
  permissions:
    - resources: [devices]
      verbs: [read, write]
      resourceNames: ["miner/*"]
    - resources: [devices]
      verbs: [read]
      resourceNames: ["powermeter/*"]
  ```

### Edge Case 3: Naming, Scoping & Version Parity
* **`<name>`**: Lowercase kebab-case slug (`^[a-z0-9][a-z0-9._-]*$`). No uppercase letters, spaces, or slashes.
* **`id`**: Immutable reverse-DNS format (`^[a-z][a-z0-9]*(\.[a-z0-9][a-z0-9-]*)+$`, e.g. `io.tether.<name>`).
* **`package.json` Name**: Defaults to `@tetherto/mdk-app-<name>` (or `@<scope>/mdk-app-<name>` if custom org specified).
* **Version Parity**: `package.json#version` and `mdk-app.yaml#version` **must match byte-for-byte** (defaults to `0.1.0`).

### Edge Case 4: Route Namespacing in `plugin/mdk-plugin.json`
* **The Gateway adds the prefix**: The Gateway serves every route of an app under `/apps/<name>`, where `<name>` is the app's
  `spec.apps[].name` in `mdk.yaml`. Declare paths **without** that prefix:
  * Example: `/status` in `mdk-plugin.json` is served at `/apps/sentinel/status`.
  * Never write `/apps/<name>/...` in the route table; it would be served at `/apps/<name>/apps/<name>/...`.
* **Root mount**: An app whose client calls fixed root paths (the agent app's `/agent/sessions`, an identity app's `/oauth/...`)
  sets `mount: /` on its `spec.apps` entry instead, and its paths are served as written. Prefixed is the default because it
  keeps installed apps from colliding.

### Edge Case 5: Dynamic UI Shell Module Contract
* The UI entry point (`ui/index.js`) is read dynamically by the UI shell.
* It must export a default object with:
  ```javascript
  export default {
    id: 'io.tether.<name>',
    displayName: '<DisplayName>',
    routes: [],
    panels: []
  };
  ```
* **Sidebar sections (optional)**: A route may name a `section` (e.g. `section: 'Operations'`) to be listed in a sidebar
  group with the other pages of that section. To give a section an icon, add `sections: [{ label: 'Operations', icon: OperationsNavIcon }]`,
  with `label` matching the routes' `section` and `icon` a React component. Omit both for a flat list; never add a
  `sections` entry with an empty or duplicate `label`. The shell template [`README.md`](../../../../../examples/mdk-ui-shell-template/README.md)
  documents every route field.
* **Building the pages**: the scaffolded `ui-src/` has one page, one hook and one Home panel. To add pages, panels or
  reports, follow [`mdk-ui-component`](../mdk-ui-component/SKILL.md), which covers the module contract, the build and

From tetherto/mdk, Apache-2.0.

More from tetherto/mdk