@multiplatform.one/cli 6.0.4 → 6.3.0

package/templates/app/AGENTS.md

@@ -0,0 +1,142 @@
+# AGENTS.md — multiplatform.one conventions
+
+Machine-readable house rules for humans and coding agents. Prefer this file over
+reconstructing conventions from meeting notes. Detailed standards live under
+`agent-os/standards/`; the living UX rulebook is linked below.
+
+## Workspace layout
+
+| Path               | Role                                                                |
+| ------------------ | ------------------------------------------------------------------- |
+| `apps/<name>/`     | Private applications (not published)                                |
+| `features/<name>/` | Feature modules for the matching app (screens, stories, playground) |
+| `packages/`        | Private app-integration packages (`@package/*`)                     |
+| `public/`          | Published `@multiplatform.one/*` packages                           |
+
+**App ↔ features twin:** every product app `apps/<name>` MUST have `features/<name>`.
+Platform/tooling shells (frappe, keycloak, storybook\*, vocs, vscode, webext, chain
+shells) are exempt in the convention linter; consumer apps from `mpo init --app`
+are not. Prefer feature code in `features/`, thin wiring in `apps/`.
+
+**Internal deps:** monorepo packages use `workspace:*`. Consumer / app-only
+templates use semver ranges from npm (`@multiplatform.one/*`).
+
+## Package boundaries
+
+| Package                         | Owns                                                 | Must not                               |
+| ------------------------------- | ---------------------------------------------------- | -------------------------------------- |
+| `@multiplatform.one/theme`      | Knobs, presets, intents, recipes, `useResolvedKnobs` | App screens                            |
+| `@multiplatform.one/components` | Catalog UI (layouts, surfaces, feedback, …)          | Frappe/API assumptions                 |
+| `@multiplatform.one/forms`      | Fields, Form, InputParts, field contracts            | Table chrome / Frappe fetch            |
+| `@multiplatform.one/table`      | DataTable, cells, filters, URL table state           | Frappe/API assumptions                 |
+| `@multiplatform.one/frappe-ui`  | Frappe adapters (`FrappeTable`, field registry)      | Re-implementing table/forms primitives |
+| `@multiplatform.one/frappe`     | Frappe client / live query                           | UI                                     |
+
+Dependency direction: `frappe-ui` → `table` / `forms` / `components` / `theme`.
+`table` and `forms` do not depend on `frappe-ui` or `frappe`.
+
+### Import rules (enforced)
+
+1. **No raw `tamagui` outside `public/`** — apps, features, and packages import
+   `@multiplatform.one/components`, `@multiplatform.one/forms`, or
+   `@multiplatform.one/theme` instead.
+2. **Apps never relative-import `public/`** — use package names
+   (`@multiplatform.one/…`), never `../../../public/…`.
+3. **No `.css` files in `apps/*`** (except ignored bench/vendor trees) — styling
+   goes through Tamagui + knobs.
+4. **No hex color literals in `features/**`** — use theme tokens (`$color10`,
+   semantic ramps, knob recipes).
+
+Run: `pnpm lint` (oxlint + `scripts/lint-conventions.mjs`).
+
+## Knobs system (canonical)
+
+Structural styling (radius, space, elevation, typography, animation) is independent
+of Tamagui color themes. Full standard: `agent-os/standards/frontend/knobs-system.md`.
+
+```tsx
+const { knobProps, control, text, elevation } = useResolvedKnobs({
+  intent, // "error" | "accent" | "warning" | "success"
+  component: "Button",
+  compact,
+});
+
+<View
+  {...knobProps.surface}
+  {...knobProps.borderRadius}
+  {...knobProps.panelPadding}
+  {...knobProps.gap}
+  {...knobProps.body}
+  hoverStyle={{ ...control.hoverKnobProps }}
+  pressStyle={{ ...control.pressKnobProps }}
+  focusVisibleStyle={{ ...control.focusVisibleKnobProps }}
+/>;
+```
+
+Rules:
+
+- Always spread complete `knobProps.*` fragments — never cherry-pick resolved tokens.
+- `resolveKnobs()` is the only canonical mapping from abstract knobs → Tamagui props.
+- Consumer `{...props}` come last (explicit eject), not internal defaults that fight recipes.
+- Presets cascade (`<Preset preset="…" theme="…">`); nested `overrides` merge by key.
+- One knob flip restyles the screen (LC-18 KNOB-TOTALITY), or the knob is broken.
+
+## Forms contract
+
+Standard refs: `agent-os/standards/frontend/field-architecture.md`,
+`field-layout.md`, `form-colors.md`, `input-parts.md`.
+
+- Initialize with `useFormField()` + `useResolvedValidators()`.
+- Three-branch render: skeleton → standalone → form-integrated (`<Field>`).
+- Canonical change prop is `onChange(value)` (LC-14). Deprecated aliases may fire
+  but must not be the only path.
+- Field slot order: Label → Hint → Error → Control; error replaces helper in one slot.
+- Use form color ramps from `shared/colorRamps.ts` — no hardcoded color tokens.
+- Fields auto-detect `useIsInTableCell()` and render chromeless inside cells.
+- Capability surfaces (camera, geo, …) MUST preflight before mount (LC-19).
+
+## Table contract
+
+Standard ref: `public/table/README.md` (package boundaries), cell/editor anatomy in
+the living rulebook.
+
+- `@multiplatform.one/table` is framework-agnostic display/filter/sort/paginate.
+- Cell editors larger than the anchor use popover (web) / sheet (native) — never
+  grow the row (LC-06). Editor popups dismiss only on dismissal intent (LC-21).
+- Frappe integration belongs in `@multiplatform.one/frappe-ui` (`FrappeTable`,
+  registry adapters), not in `table`.
+- Child-table / TableInput follow the same field `onChange` contract as forms.
+
+## Living rulebook
+
+**Normative UX + composition rules (LC-\* and recipe taxonomy):**
+
+→ [`docs/theme-propagation-spec.md`](./docs/theme-propagation-spec.md)
+
+That document is the living rulebook: every owner-reported spacing/UX issue is
+adjudicated there in-session as VIOLATION or GAP (new LC-\* rule + VERIFY). Agents
+changing catalog components MUST read it first; a contradicting change updates the
+spec in the same change. Companion docs:
+
+- Catalog guidelines: `docs/design-guidelines.md` + `docs/design-guidelines-blueprint.md`
+- Click-matrix / VERIFY arm: `docs/storybook-knob-edge-cases.md`
+- Agent OS standards index: `agent-os/standards/index.yml`
+
+## Tooling
+
+| Command                 | Purpose                                                        |
+| ----------------------- | -------------------------------------------------------------- |
+| `pnpm lint`             | oxlint (incl. convention rules) + structural convention checks |
+| `pnpm lint:conventions` | Structural checks only (css twin, features twin)               |
+| `pnpm format`           | oxfmt                                                          |
+| `pnpm ci:local`         | format + lint + typecheck + build + test + tree-clean          |
+
+Use **oxlint / oxfmt**, not ESLint / Prettier
+(`agent-os/standards/global/linting-formatting.md`).
+
+## Coding defaults
+
+- Named exports only; cut dead/legacy aliases unless a task explicitly needs them.
+- Cross-platform: shared code first; `.native.tsx` / `.web.tsx` only when required.
+- Stories and tests live next to the component / feature they cover.
+- Deeper style rules: `agent-os/standards/global/coding-style.md`.

package/templates/app/README.md

@@ -0,0 +1,62 @@
+# **NAME**
+
+App-only project scaffolded by [`@multiplatform.one/cli`](https://www.npmjs.com/package/@multiplatform.one/cli)
+(`mpo init --app` / `create-multiplatform-app`).
+
+This is **not** a fork of the multiplatform.one monorepo. Framework packages come from npm at
+semver ranges (`@multiplatform.one/*`: `__MPO_VERSION__`), never `workspace:*`.
+
+## Layout
+
+| Path                 | Role                                                      |
+| -------------------- | --------------------------------------------------------- |
+| `apps/__NAME__/`     | App shell (Vite + React web stub)                         |
+| `features/__NAME__/` | Feature screens / UI — import from here, not from `apps/` |
+| `packages/config/`   | Shared app config (`@package/config`)                     |
+
+Convention: every `apps/<name>` has a matching `features/<name>`.
+
+## Commands
+
+```bash
+pnpm install
+pnpm dev       # start the web stub
+pnpm build
+pnpm lint
+pnpm typecheck
+```
+
+## Dependencies
+
+Feature and app packages depend on published framework packages, for example:
+
+```json
+{
+  "@multiplatform.one/components": "__MPO_VERSION__",
+  "@multiplatform.one/theme": "__MPO_VERSION__",
+  "@multiplatform.one/platform": "__MPO_VERSION__"
+}
+```
+
+Upgrade with your usual package manager (`pnpm update @multiplatform.one/*`).
+
+## Conventions
+
+See [`AGENTS.md`](./AGENTS.md) for package boundaries, the apps ↔ features twin,
+import rules (no raw `tamagui` outside framework packages, no relative `public/`
+imports, no hex literals in features), and knobs/forms/table contracts.
+
+## Next steps
+
+1. Replace the stub `HomeScreen` in `features/__NAME__/src/HomeScreen.tsx`.
+2. Add routes / screens under `features/__NAME__/`.
+3. When you need native (Expo / one), extend `apps/__NAME__/` — keep business UI in `features/`.
+4. Do **not** copy `public/` from the framework monorepo into this project.
+
+## Create another app
+
+```bash
+mpo init --app another-app
+# or
+npx --package=@multiplatform.one/cli create-multiplatform-app another-app
+```

package/templates/app/apps/__NAME__/index.html

@@ -0,0 +1,36 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>__NAME_PASCAL__</title>
+    <!--
+      LC-33 FONT-STABLE-MOUNT: the shell owns Inter (the theme package does
+      not inject @font-face as a CSS side effect). Preload + a head face with
+      font-display: optional means first paint already renders Inter and the
+      face never swaps after mount. The binaries live in public/fonts/.
+    -->
+    <link rel="preload" href="/fonts/inter-400.woff2" as="font" type="font/woff2" crossorigin />
+    <link rel="preload" href="/fonts/inter-700.woff2" as="font" type="font/woff2" crossorigin />
+    <style data-font-inter>
+      @font-face {
+        font-family: "Inter";
+        font-style: normal;
+        font-weight: 400;
+        font-display: optional;
+        src: url("/fonts/inter-400.woff2") format("woff2");
+      }
+      @font-face {
+        font-family: "Inter";
+        font-style: normal;
+        font-weight: 700;
+        font-display: optional;
+        src: url("/fonts/inter-700.woff2") format("woff2");
+      }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/app/apps/__NAME__/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@app/__NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@features/__NAME__": "workspace:*",
+    "@multiplatform.one/components": "__MPO_VERSION__",
+    "@multiplatform.one/platform": "__MPO_VERSION__",
+    "@multiplatform.one/theme": "__MPO_VERSION__",
+    "@package/config": "workspace:*",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "react-native-web": "^0.21.2",
+    "tamagui": "2.0.0-rc.41"
+  },
+  "devDependencies": {
+    "@types/react": "~19.2.14",
+    "@types/react-dom": "~19.2.3",
+    "@vitejs/plugin-react": "^6.0.2",
+    "typescript": "~5.9.3",
+    "vite": "^8.0.10"
+  }
+}

package/templates/app/apps/__NAME__/src/App.tsx

@@ -0,0 +1,9 @@
+import { HomeScreen } from "@features/__NAME__";
+
+/**
+ * App shell for __NAME__.
+ * Wire providers / routing here; keep screens in features/__NAME__.
+ */
+export function App() {
+  return <HomeScreen />;
+}

package/templates/app/apps/__NAME__/src/main.tsx

@@ -0,0 +1,14 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App";
+
+const root = document.getElementById("root");
+if (!root) {
+  throw new Error("#root element missing");
+}
+
+createRoot(root).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/templates/app/apps/__NAME__/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["vite/client"]
+  },
+  "include": ["./src/**/*"],
+  "exclude": ["**/node_modules/**"]
+}

package/templates/app/apps/__NAME__/vite.config.ts

@@ -0,0 +1,17 @@
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 3456,
+  },
+  resolve: {
+    alias: {
+      "react-native": "react-native-web",
+    },
+  },
+  optimizeDeps: {
+    include: ["react", "react-dom", "react-native-web"],
+  },
+});

package/templates/app/features/__NAME__/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@features/__NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts",
+    "./HomeScreen": "./src/HomeScreen.tsx"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@multiplatform.one/components": "__MPO_VERSION__",
+    "@multiplatform.one/platform": "__MPO_VERSION__",
+    "@multiplatform.one/theme": "__MPO_VERSION__",
+    "@package/config": "workspace:*",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "react-native-web": "^0.21.2",
+    "tamagui": "2.0.0-rc.41"
+  },
+  "devDependencies": {
+    "@types/react": "~19.2.14",
+    "@types/react-dom": "~19.2.3",
+    "typescript": "~5.9.3"
+  },
+  "peerDependencies": {
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  }
+}

package/templates/app/features/__NAME__/src/HomeScreen.tsx

@@ -0,0 +1,70 @@
+import type { CSSProperties } from "react";
+
+/**
+ * Feature screen for __NAME__.
+ *
+ * Keep product UI in features/<name>. The app shell (apps/<name>) should only
+ * wire providers, routing, and platform entry points.
+ *
+ * Prefer importing from @multiplatform.one/components once you add Tamagui
+ * providers (see apps/__NAME__/src/main.tsx). This stub stays dependency-light
+ * so `pnpm dev` works immediately after scaffold.
+ */
+export function HomeScreen() {
+  return (
+    <main style={styles.main}>
+      <p style={styles.eyebrow}>multiplatform.one</p>
+      <h1 style={styles.title}>__NAME_PASCAL__</h1>
+      <p style={styles.body}>
+        App-only scaffold. Framework packages resolve from npm at semver ranges — not{" "}
+        <code>workspace:*</code>.
+      </p>
+      <ul style={styles.list}>
+        <li>
+          <code>apps/__NAME__</code> — shell
+        </li>
+        <li>
+          <code>features/__NAME__</code> — screens (you are here)
+        </li>
+        <li>
+          <code>packages/config</code> — shared config
+        </li>
+      </ul>
+    </main>
+  );
+}
+
+const styles: Record<string, CSSProperties> = {
+  main: {
+    fontFamily:
+      'ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
+    maxWidth: 560,
+    margin: "0 auto",
+    padding: "4rem 1.5rem",
+    color: "#0f172a",
+  },
+  eyebrow: {
+    margin: 0,
+    fontSize: 12,
+    letterSpacing: "0.08em",
+    textTransform: "uppercase",
+    color: "#64748b",
+  },
+  title: {
+    margin: "0.5rem 0 1rem",
+    fontSize: "2.25rem",
+    lineHeight: 1.15,
+  },
+  body: {
+    margin: "0 0 1.5rem",
+    fontSize: 16,
+    lineHeight: 1.55,
+    color: "#334155",
+  },
+  list: {
+    margin: 0,
+    paddingInlineStart: "1.25rem",
+    color: "#334155",
+    lineHeight: 1.8,
+  },
+};

package/templates/app/features/__NAME__/src/index.ts

@@ -0,0 +1 @@
+export { HomeScreen } from "./HomeScreen";

package/templates/app/features/__NAME__/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["./src/**/*"],
+  "exclude": ["**/node_modules/**"]
+}

package/templates/app/gitignore

@@ -0,0 +1,8 @@
+node_modules
+dist
+.turbo
+.vite
+*.log
+.env
+.env.local
+.DS_Store

package/templates/app/npmrc

@@ -0,0 +1,2 @@
+auto-install-peers=true
+strict-peer-dependencies=false

package/templates/app/oxlintrc.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "rules": {
+    "no-unused-vars": [
+      "warn",
+      {
+        "argsIgnorePattern": "^_",
+        "varsIgnorePattern": "^_"
+      }
+    ],
+    "no-console": "warn",
+    "eqeqeq": "error",
+    "no-var": "error",
+    "prefer-const": "error"
+  },
+  "overrides": [
+    {
+      "files": [
+        "apps/**/*.{ts,tsx,js,jsx}",
+        "features/**/*.{ts,tsx,js,jsx}",
+        "packages/**/*.{ts,tsx,js,jsx}"
+      ],
+      "rules": {
+        "no-restricted-imports": [
+          "error",
+          {
+            "paths": [
+              {
+                "name": "tamagui",
+                "message": "Raw tamagui is only allowed inside framework packages. Import from @multiplatform.one/components, @multiplatform.one/forms, or @multiplatform.one/theme. See AGENTS.md."
+              }
+            ]
+          }
+        ]
+      }
+    }
+  ],
+  "ignorePatterns": ["**/node_modules/**", "**/dist/**", "**/build/**"]
+}

package/templates/app/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "__NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "description": "__NAME__ — multiplatform.one app",
+  "license": "MIT",
+  "scripts": {
+    "dev": "pnpm --filter @app/__NAME__ dev",
+    "build": "pnpm --filter @app/__NAME__ build",
+    "lint": "oxlint -c oxlintrc.json .",
+    "typecheck": "pnpm -r typecheck"
+  },
+  "devDependencies": {
+    "oxlint": "^1.62.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@10.32.1"
+}

package/templates/app/packages/config/config.json

@@ -0,0 +1,4 @@
+{
+  "private": ["SECRET"],
+  "public": ["BASE_URL", "DEBUG", "I18N_DEFAULT_LANGUAGE"]
+}

package/templates/app/packages/config/index.ts

@@ -0,0 +1,5 @@
+import configJson from "./config.json";
+
+export const config = configJson;
+export type AppConfig = typeof configJson;
+export default config;

package/templates/app/packages/config/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@package/config",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./config.json": "./config.json"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.3"
+  }
+}

package/templates/app/packages/config/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["./**/*"],
+  "exclude": ["**/node_modules/**"]
+}

package/templates/app/pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+packages:
+  - apps/*
+  - features/*
+  - packages/*

package/templates/app/tsconfig.base.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true
+  }
+}