@multiplatform.one/cli 7.10.0 → 7.15.0

package/src/source.spec.ts

@@ -0,0 +1,45 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { isGitUrl, monorepoCheckout, resolveSource } from "./source";
+
+const monorepo = fileURLToPath(new URL("../../..", import.meta.url)).replace(/\/$/, "");
+
+describe("resolveSource", () => {
+  it("flags win, with HEAD for a path and main for a url", () => {
+    expect(resolveSource({ source: "/tmp/mpo" })).toEqual({
+      source: "/tmp/mpo",
+      ref: "HEAD",
+      origin: "flag",
+    });
+    expect(resolveSource({ source: "https://example.com/mpo.git" })).toEqual({
+      source: "https://example.com/mpo.git",
+      ref: "main",
+      origin: "flag",
+    });
+    expect(resolveSource({ source: "/tmp/mpo", checkout: "v7.11.0" }).ref).toBe("v7.11.0");
+  });
+
+  it("a CLI running inside the monorepo scaffolds from that checkout's HEAD", () => {
+    expect(monorepoCheckout()).toBe(monorepo);
+    expect(existsSync(join(monorepo, "apps/one/package.json"))).toBe(true);
+    const spec = resolveSource();
+    expect(spec).toEqual({ source: monorepo, ref: "HEAD", origin: "monorepo" });
+    expect(resolveSource({ checkout: "main" }).ref).toBe("main");
+  });
+
+  it("recognizes git urls", () => {
+    for (const url of [
+      "https://git.corp.bitspur.com/multiplatform.one/mpo.git",
+      "ssh://git@host/repo.git",
+      "git@github.com:org/repo.git",
+      "file:///tmp/repo",
+    ]) {
+      expect(isGitUrl(url), url).toBe(true);
+    }
+    for (const path of ["/tmp/repo", "../repo", "repo"]) {
+      expect(isGitUrl(path), path).toBe(false);
+    }
+  });
+});

package/src/source.ts

@@ -0,0 +1,88 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { cliRoot, cliVersion } from "./commands/provenance";
+
+export const monorepoUrl = "https://git.corp.bitspur.com/multiplatform.one/mpo.git";
+
+export interface SourceSpec {
+  /** Path to a local clone, or a git URL. */
+  source: string;
+  /** Commit, tag or branch to scaffold from. */
+  ref: string;
+  /**
+   * flag     = --source / --checkout
+   * monorepo = the CLI runs from inside a monorepo checkout (dev, `make`)
+   * stamp    = lib/source.json written by the build
+   * tag      = no stamp: the release tag of this CLI version
+   */
+  origin: "flag" | "monorepo" | "stamp" | "tag";
+  warning?: string;
+}
+
+export interface SourceStamp {
+  cliVersion?: string;
+  sha?: string;
+  url?: string;
+}
+
+export function isGitUrl(source: string): boolean {
+  return /^(https?|ssh|git|file):\/\//.test(source) || /^[\w.-]+@[\w.-]+:/.test(source);
+}
+
+/** The monorepo checkout this CLI runs from, if any (src via tsx, or the workspace link). */
+export function monorepoCheckout(): string | undefined {
+  const root = resolve(cliRoot(), "../..");
+  if (
+    existsSync(join(root, "apps/one/package.json")) &&
+    existsSync(join(root, "public/cli/package.json"))
+  ) {
+    return root;
+  }
+  return undefined;
+}
+
+export function readSourceStamp(): SourceStamp | undefined {
+  try {
+    return JSON.parse(readFileSync(join(cliRoot(), "lib/source.json"), "utf-8")) as SourceStamp;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Where `mpo init` clones from. Flags win; a CLI running inside the monorepo
+ * uses that checkout's HEAD; a published CLI uses the commit stamped at build
+ * time; a build without a stamp falls back to the release tag of its own
+ * version, and `init` retries `main` when that tag is missing.
+ */
+export function resolveSource(flags: { source?: string; checkout?: string } = {}): SourceSpec {
+  if (flags.source) {
+    return {
+      source: flags.source,
+      ref: flags.checkout ?? (isGitUrl(flags.source) ? "main" : "HEAD"),
+      origin: "flag",
+    };
+  }
+  const checkout = monorepoCheckout();
+  if (checkout) {
+    return { source: checkout, ref: flags.checkout ?? "HEAD", origin: "monorepo" };
+  }
+  const stamp = readSourceStamp();
+  const url = stamp?.url ?? monorepoUrl;
+  if (flags.checkout) {
+    return { source: url, ref: flags.checkout, origin: "flag" };
+  }
+  if (stamp?.sha) {
+    return { source: url, ref: stamp.sha, origin: "stamp" };
+  }
+  const version = cliVersion();
+  const ref = version ? `v${version}` : "main";
+  return {
+    source: url,
+    ref,
+    origin: "tag",
+    warning:
+      `this build of @multiplatform.one/cli carries no source commit (lib/source.json); ` +
+      `scaffolding from ${ref} instead`,
+  };
+}

package/templates/AGENTS.md

@@ -0,0 +1,161 @@
+# AGENTS.md — conventions for this project
+
+Machine-readable house rules for humans and coding agents. Prefer this file
+over reconstructing conventions from history.
+
+## What this repository is
+
+The multiplatform.one monorepo at one commit, pruned. `.mpo.json` records the
+source commit and url, the product apps and the services kept. `mpo update`
+merges later monorepo commits in as a three-way merge that keeps your commits;
+`mpo add-app <name>` adds a product app. Neither is committed for you.
+
+The published `@multiplatform.one/*` packages come from the registry at the
+semver range in each `package.json`. There is no copy of them here: a change to
+one of them is made upstream, in the monorepo, and arrives with the next
+`mpo update`.
+
+## Workspace layout
+
+| Path               | Role                                                                |
+| ------------------ | ------------------------------------------------------------------- |
+| `apps/<name>/`     | Product apps and the services kept at init (frappe, keycloak, …)    |
+| `features/<name>/` | Feature modules for the matching app (screens, stories, playground) |
+| `packages/`        | Private app-integration packages (`@package/*`)                     |
+
+**App ↔ features twin:** every product app `apps/<name>` MUST have
+`features/<name>`. Services are exempt in the convention linter; product apps
+are not. Prefer feature code in `features/`, thin wiring in `apps/`.
+
+**Delivery targets live INSIDE the product app**, not as sibling shells:
+`apps/<name>/routes/` (One web + native), `apps/<name>/tauri/` (webview
+desktop shell), `apps/<name>/gnome/` (GTK4/GJS native-widget desktop),
+`apps/<name>/webext/` (browser extension) and `apps/<name>/vscode/` (VS Code
+extension), each with a sibling `vite.config.<target>.ts`. Tauri and GNOME are
+peer desktop targets; pick per product. All targets mount the same `features/`
+code behind ONE routing layer: One's router API, backed on non-One hosts by the
+stack-navigation seam (`@multiplatform.one/router/seam`).
+
+**Internal deps:** private workspace packages use `workspace:*`;
+`@multiplatform.one/*` use the registry range.
+
+## Which package for what
+
+| Package                         | Owns                                                                      |
+| ------------------------------- | ------------------------------------------------------------------------- |
+| `@multiplatform.one/theme`      | Knobs, presets, intents, recipes, `useResolvedKnobs`                      |
+| `@multiplatform.one/components` | Catalog UI (layouts, surfaces, feedback, …)                               |
+| `@multiplatform.one/forms`      | Fields, Form, InputParts, field contracts, form color ramps               |
+| `@multiplatform.one/table`      | DataTable, cells, filters, URL table state                                |
+| `@multiplatform.one/frappe-ui`  | Frappe adapters (`FrappeTable`, field registry)                           |
+| `@multiplatform.one/frappe`     | Frappe client / live query                                                |
+| `@multiplatform.one/backoffice` | Embeddable desk recreation (BackofficeProvider, shell/list/form surfaces) |
+
+`table` and `forms` know nothing of Frappe; Frappe integration belongs in
+`frappe-ui`. `features/backoffice` is a thin wrapper over
+`@multiplatform.one/backoffice` (host wiring: one-router adapter, env-derived
+frappe config, scheme adapter).
+
+### Import rules (enforced)
+
+1. **No raw `tamagui`** in `apps/`, `features/` or `packages/`: import
+   `@multiplatform.one/components`, `@multiplatform.one/forms` or
+   `@multiplatform.one/theme` instead (`oxlintrc.json`, no-restricted-imports).
+2. **No `*.css` files in `apps/*`** (except ignored bench/vendor trees): styling
+   goes through Tamagui + knobs.
+3. **No hex color literals in `apps/`, `packages/` or `features/`**: use
+   theme tokens (`$color10`, semantic ramps, knob recipes). A file no token
+   reaches (GTK widget CSS, a content script, Expo build config) opts out with
+   a `// hex-escape: <reason>` comment that says why.
+
+Run: `pnpm lint` (oxlint + `scripts/lint-conventions.mjs`).
+
+## Knobs system (canonical)
+
+Structural styling (radius, space, elevation, typography, animation) is
+independent of Tamagui color themes. `useResolvedKnobs` comes from
+`@multiplatform.one/theme`.
+
+```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, or the knob is broken.
+
+## Forms contract
+
+- Initialize with `useFormField()` + `useResolvedValidators()`.
+- Three-branch render: skeleton → standalone → form-integrated (`<Field>`).
+- Canonical change prop is `onChange(value)`. 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 the form color ramps exported by `@multiplatform.one/forms`
+  (`formCommonColors`, `formDropzoneColors`); no hardcoded color tokens.
+- Fields auto-detect `useIsInTableCell()` and render chromeless inside cells.
+- Capability surfaces (camera, geo, …) MUST preflight before mount.
+
+## Table contract
+
+- `@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. Editor popups dismiss only on dismissal intent.
+- 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.
+
+## Screen data states
+
+Every screen-level data fetch, not only Frappe, MUST render loading, empty,
+error and ready through `AsyncBoundary`, `EmptyState` and `Skeleton` from
+`@multiplatform.one/components`. A bare
+`error ? <Paragraph color="$color11">` branch is a defect. Empty ≠ error ≠
+loading.
+
+## Tooling
+
+| Command                 | Purpose                                                        |
+| ----------------------- | -------------------------------------------------------------- |
+| `pnpm dev`              | The first product app's dev server (`dev:<name>` when several) |
+| `pnpm build`            | Build every workspace package except the apps                  |
+| `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 + verify + tree-clean |
+| `pnpm doctor:npmrc`     | Check registry auth and the installed workspace linker         |
+
+Use **oxlint / oxfmt**, not ESLint / Prettier. Per-app targets are
+`make <name>/<target>` from the root `Makefile`.
+
+Install layout settings live in `pnpm-workspace.yaml`, including
+`nodeLinker: hoisted`. `@react-gnome/*` and `@multiplatform.one/*` both resolve
+from npmjs, the default registry, so an install needs no token.
+`pnpm doctor:npmrc` reports missing or empty auth
+as advisory and fails if the installed tree records a different linker from the
+workspace; an existing isolated tree needs `pnpm install` to repair its layout.
+
+## 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.

package/templates/README.md

@@ -0,0 +1,62 @@
+# multiplatform.one project
+
+Web, iOS and Android from one React + Tamagui tree, with desktop, browser
+extension and VS Code targets inside each product app. This repository is the
+[multiplatform.one](https://git.corp.bitspur.com/multiplatform.one/mpo)
+monorepo at one commit, pruned to the product apps and services picked at
+`mpo init`. `.mpo.json` records the commit and the selection, and `AGENTS.md`
+holds the conventions.
+
+## Layout
+
+| Path               | What lives there                                       |
+| ------------------ | ------------------------------------------------------ |
+| `apps/<name>/`     | Each product app, and the services kept at init        |
+| `features/<name>/` | Screens and feature code for the matching app          |
+| `packages/`        | Private app packages (`@package/app`, themes, i18n, …) |
+
+The `@multiplatform.one/*` packages come from the registry.
+
+## Getting started
+
+Prerequisites: Node 20+, pnpm 10+ and git.
+
+```sh
+pnpm install
+pnpm dev            # the first product app (dev:<name> picks one of several)
+```
+
+`.env` starts as a copy of `.env.example`.
+
+<!-- service:frappe -->
+
+## Frappe
+
+`apps/frappe` is the dev bench. `make frappe/bootstrap` creates it once, and
+`make frappe/dev` starts the services it needs from `docker/compose.yaml` and
+serves it on `FRAPPE_PORT` (`http://localhost:8000`), which also proxies the
+web dev server same-origin. The apps reach it through `createApp` in
+`packages/app/app.tsx` while `FRAPPE_ENABLED=1`.
+
+<!-- /service:frappe -->
+<!-- no-service:frappe -->
+
+## Frappe
+
+This project runs no Frappe server of its own. The apps keep the Frappe
+client: `createApp` in `packages/app/app.tsx` mounts the `FrappeProvider`
+while `FRAPPE_ENABLED=1` and talks to `BASE_URL`, or to the `baseURL` passed
+in `frappe: { baseURL }`. Point it at a Frappe server, or hand it a fixture
+corpus (`frappe: { fixtures }`, an `InMemoryFixtureProvider` from
+`@multiplatform.one/frappe`) and run with no server at all.
+
+<!-- /no-service:frappe -->
+
+## Updating
+
+```sh
+pnpm exec mpo update    # needs a clean tree; the merge lands uncommitted
+git add -A && git commit -m "chore: mpo update"
+```
+
+`pnpm exec mpo add-app <name>` adds a product app the same way.

package/templates/pieces/frappe/universal/README.md.partial

@@ -1,37 +1,12 @@
-## Frappe backend (`mpo init --frappe`)
+## Frappe client (`frappe` piece)
 
 `apps/__NAME__/src/app.ts` wires `createApp({ frappe: … })`: the
-`FrappeProvider` mounts when `FRAPPE_ENABLED=1` and talks to `FRAPPE_URL`
-(both are `public` env keys in `packages/config/config.json`, loaded from
-`.env` — start from `.env.example`).
+`FrappeProvider` mounts when `FRAPPE_ENABLED=1` and talks to the Frappe server
+at `FRAPPE_URL` (both are `public` env keys in `packages/config/config.json`,
+loaded from `.env` — start from `.env.example`). This piece brings no server
+of its own; add the `frappe-bench` piece for a dev server in docker.
 
-Run a dev bench with docker:
-
-```bash
-docker compose -f docker/compose.frappe.yaml up -d
-docker compose -f docker/compose.frappe.yaml exec bench bash
-
-# inside the container (first time only)
-bench init --skip-redis-config-generation frappe-bench
-cd frappe-bench
-bench set-config -g db_host mariadb
-bench set-config -g redis_cache redis://redis-cache:6379
-bench set-config -g redis_queue redis://redis-queue:6379
-bench set-config -g redis_socketio redis://redis-queue:6379
-bench new-site __NAME__.localhost \
-  --mariadb-user-host-login-scope=% \
-  --db-root-password frappe --admin-password admin
-bench --site __NAME__.localhost set-config developer_mode 1
-
-# every dev session
-bench start
-```
-
-Then set `FRAPPE_URL=http://__NAME__.localhost:8000` (or keep
-`http://localhost:8000` and make the site the default with
-`bench use __NAME__.localhost`) and restart `pnpm dev`.
-
-### Running against fixtures, with no bench
+### Running against fixtures, with no server
 
 `createApp` takes a fixture corpus, so the app runs with no server and no
 network. Hand `frappe.fixtures` a `FixtureProvider` in
@@ -85,5 +60,5 @@ const fixtures = new InMemoryFixtureProvider({
 Leave it out and the table still renders its rows; it just has no
 metadata-derived filter fields.
 
-To point the same app at a real bench again, drop `fixtures` and set
+To point the same app at a real Frappe server again, drop `fixtures` and set
 `FRAPPE_ENABLED=1` + `FRAPPE_URL` in `.env`.

package/templates/pieces/frappe/universal/env.example.partial

@@ -1,8 +1,8 @@
-# Frappe backend (mpo init --frappe) — copy to .env. Keys listed as `public`
+# Frappe client (the frappe piece) — copy to .env. Keys listed as `public`
 # in packages/config/config.json are baked into the client bundle at build
 # time (VITE_MP_CONFIG); FRAPPE_ENABLED=1 mounts the FrappeProvider wired in
 # apps/__NAME__/src/app.ts.
 FRAPPE_ENABLED=1
-# Bench URL the client talks to (docker/compose.frappe.yaml serves :8000).
-# Falls back to BASE_URL, then http://localhost:8000.
+# The Frappe server the client talks to. Falls back to BASE_URL, then
+# http://localhost:8000.
 FRAPPE_URL=http://localhost:8000

package/templates/pieces/frappe-bench/universal/README.md.partial

@@ -0,0 +1,28 @@
+## Frappe dev bench (`frappe-bench` piece)
+
+`docker/compose.frappe.yaml` runs a dev bench with its MariaDB and Redis:
+
+```bash
+docker compose -f docker/compose.frappe.yaml up -d
+docker compose -f docker/compose.frappe.yaml exec bench bash
+
+# inside the container (first time only)
+bench init --skip-redis-config-generation frappe-bench
+cd frappe-bench
+bench set-config -g db_host mariadb
+bench set-config -g redis_cache redis://redis-cache:6379
+bench set-config -g redis_queue redis://redis-queue:6379
+bench set-config -g redis_socketio redis://redis-queue:6379
+bench new-site __NAME__.localhost \
+  --mariadb-user-host-login-scope=% \
+  --db-root-password frappe --admin-password admin
+bench --site __NAME__.localhost set-config developer_mode 1
+
+# every dev session
+bench start
+```
+
+It serves `http://localhost:8000`. With the `frappe` piece, set
+`FRAPPE_URL=http://__NAME__.localhost:8000` (or keep `http://localhost:8000`
+and make the site the default with `bench use __NAME__.localhost`) and restart
+`pnpm dev`.

package/templates/pieces/{frappe → frappe-bench}/universal/docker/compose.frappe.yaml

@@ -1,11 +1,11 @@
-# Dev Frappe bench for __NAME__ (mpo init --frappe).
+# Dev Frappe bench for __NAME__ (the frappe-bench piece).
 #
 #   docker compose -f docker/compose.frappe.yaml up -d
 #   docker compose -f docker/compose.frappe.yaml exec bench bash
 #
 # The frappe/bench image is a development sandbox (frappe user + bench
 # tooling); the bench itself is created ONCE inside the container — see the
-# "Frappe backend" section of the README for the init commands. State
+# "Frappe dev bench" section of the README for the init commands. State
 # persists in the named volumes.
 services:
   bench:

package/templates/pieces/tauri/universal/README.md.partial

@@ -9,10 +9,12 @@ pnpm tauri:dev     # dev window against the vite dev server (:3456)
 pnpm tauri:build   # bundle installers (runs pnpm build first)
 ```
 
-`tauri:dev` starts `pnpm dev` for you (beforeDevCommand) and opens the
-window once http://localhost:3456 responds. Note the web build is an SSR
-One app: `tauri:build` embeds `apps/__NAME__/dist` as-is, which suits a
-static/SPA export — point `frontendDist` (src-tauri/tauri.conf.json) at
-your static output, or keep the desktop shell against a served URL.
+`tauri:dev` starts `pnpm dev` for you (beforeDevCommand); the window holds
+on a waiting page until the app's client modules answer, then loads the
+app (Cmd/Ctrl+R reloads it, Cmd/Ctrl+Alt+I toggles devtools). Note the web
+build is an SSR One app: `tauri:build` embeds `apps/__NAME__/dist` as-is,
+which suits a static/SPA export — point `frontendDist`
+(src-tauri/tauri.conf.json) at your static output, or keep the desktop
+shell against a served URL.
 Regenerate icons from your own artwork with
 `pnpm --filter @app/__NAME__ tauri icon <path/to/icon.png>`.