@wix/himalaya-cli 0.1114.0 → 0.1116.0

package/guides/himi-mcp.md

@@ -80,6 +80,14 @@ runs a session with it.
 
 Each tool acts on the agent's workspace folder unless it is given a `dir`.
 
+**File tools, for hosts that cannot edit files.** `himi mcp --with-files` adds `himi_list_apps`,
+`himi_list_files`, `himi_read_file`, `himi_write_files` and `himi_delete_files`. The Claude Desktop
+Extension uses them, because Claude Desktop chat has no file editing of its own. They follow the
+hosted connector's shapes, act only inside the workspace folder (checked on the real path, so a
+symlink cannot lead out of it), and never touch `.git`, `node_modules` or `dist`. When the host names
+no workspace, `HIMI_WORKSPACE` sets the folder. Coding agents edit files themselves, so the flag is
+off by default.
+
 **What the tools will not do:** make a release live, build store binaries, touch secrets, write to a
 site's CMS, or create a Wix site. Those spend money, handle credentials, or change what real users
 see, so they stay commands a person runs. Publishing needs a sign-in first: `himi_login` opens the

package/guides/wix-business-context.md

@@ -161,11 +161,13 @@ The plane has no headless browser (`look.unavailable: no_browser_on_plane`). Own
 `himi-brandy`, the site shell, opens the customer's live website as native-framed tabs, so its contract is a `site` block: which website, and which of its pages are tabs, drawer rows or overflow rows. `--shell brandy` derives that block into `provisioning.overlay.json`:
 
 ```bash
-himi site analyze --url https://owner.wixsite.com/site --client-id <id> --shell brandy   # writes site.pages
+himi site analyze --url https://owner.wixsite.com/site --shell brandy   # writes site.pages
 # edit site.pages in .himi/business-book/provisioning.overlay.json if the map needs it
-himi site analyze --url https://owner.wixsite.com/site --client-id <id> --shell brandy --apply
+himi site analyze --url https://owner.wixsite.com/site --shell brandy --apply
 ```
 
+No `--client-id` is needed here: a site shell is visitor-only, its pages are the site itself, and its contract binds no Headless client. For an off-repo brandy app (`himi init --template brandy`), run the `--apply` inside the app folder: it writes the derived `site` block into the package's own `provisioning.json`, which the template's `config.ts` builds every tab and screen from.
+
 The map comes from what the analysis already reads without owner credentials, because Wix has no public menu API: the published page list (`look.sitePages`), the header menu the crawl saw (`look.navLinks`, label and href), and each page's role.
 
 - **Order and labels** follow the site's own menu. Links to other hosts, and repeat links to the same page, are dropped.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1114.0",
+  "version": "0.1116.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -67,5 +67,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "0577b42d47b1e8019d8e91a63ef760878990ad8500fc4c7deec84f83"
+  "falconPackageHash": "6d8f58d4b9f65728efd1d2728c9c1567bbe8ea1cb014bda9ee1afc50"
 }

package/templates/brandy/README.md

@@ -0,0 +1,60 @@
+# __HIMI_APP_NAME__ — your website as an app
+
+A **site shell**: your live Wix website, framed as a native app. Every tab and drawer row is one of
+your site's own pages, shown in a WebView under a native tab bar, drawer and splash in your brand
+colours. The site's own header, footer and Wix ads are hidden. It is the fastest way to ship an
+existing website as an app, and each tab can later be replaced by a native screen.
+
+## Point it at your site
+
+The whole app is the `site` block in `provisioning.json`:
+
+```json
+{
+  "site": {
+    "origin": "https://your-account.wixsite.com/your-site",
+    "kind": "wix",
+    "pages": [
+      { "id": "home", "title": "Home", "path": "/", "icon": "home" },
+      { "id": "blog", "title": "Blog", "path": "/blog", "icon": "newspaper" },
+      { "id": "contact", "title": "Contact", "path": "/contact", "icon": "mail", "placement": "drawer" }
+    ],
+    "chrome": { "hideSiteHeader": true, "hideSiteFooter": true, "hideWixAds": true }
+  }
+}
+```
+
+The placeholder origin above is not a real site. Replace it by deriving the block from your site's
+own menu, from inside this folder:
+
+```bash
+himi site analyze --url https://your-account.wixsite.com/your-site --shell brandy --apply
+```
+
+That writes the derived `site` block into this `provisioning.json` and your site's colours into
+`tokens.json`. No `--client-id` is needed, because a site shell reads nothing through a Wix client.
+To review the map first, leave out `--apply`: the block is then only written to
+`.himi/business-book/provisioning.overlay.json`. You can always edit the block by hand.
+
+- **`origin`** is your published site, `https` only. A free site's path (`/your-site`) is part of it.
+- **`pages`** are paths relative to the origin. Each needs a unique `id` (`a-z`, `0-9`, `_`) and must
+  not use `page`, which is reserved.
+- **`placement`** is `tab` (the default), `drawer` or `overflow`. At most four tabs are shown, and
+  `home` must be the first of them: the app opens on its first tab.
+- **`icon`** is a design-system icon name (`home`, `bag`, `calendar`, `ticket`, `newspaper`, `mail`,
+  `info`, `tag`, `photo`, `person`, `globe`, …).
+- **`chrome`** hides the site's own header (on inner pages), its footer and the Wix ads banner.
+  Every flag defaults to hidden.
+
+`config.ts` validates the block whenever the app loads, so an `http` origin, a duplicate id or a map
+with no tab fails `himi validate`, `himi render` and `himi push` rather than shipping.
+
+## Loop
+
+```bash
+himi build && himi validate --strict   # derive the screens and check them
+himi render site_home                  # the home tab (a WebView: headless render reports it, it does not paint it)
+himi push --draft                      # publish a draft release and open the web preview
+```
+
+Your colours live in `tokens.json` and your name in `config.ts`.

package/templates/brandy/config.ts

@@ -0,0 +1,76 @@
+// Your app's configuration — a SITE SHELL. Your live website is the app: every tab and drawer
+// row is one of its pages, shown in a native-framed WebView under a native tab bar and drawer.
+//
+// Nothing here names a page. The pages come from the `site` block of ./provisioning.json, so you
+// change the app by changing that block — by hand, or with
+//   himi site analyze --url https://<your-site> --shell brandy
+// which derives it from your site's own menu. Inspect the live values any time with
+// `himi context`; see `himi docs app-config`.
+import {
+  assertSiteShellConfig,
+  defineApp,
+  siteLinkableScreens,
+  siteNav,
+  siteNavConfig,
+  type SiteShellConfig,
+} from "@himalaya/core";
+import { ConsoleTelemetrySink } from "@himalaya/telemetry-console";
+import provisioning from "./provisioning.json" with { type: "json" };
+
+/** Your website and its page map. Validated here, so a mistake in provisioning.json (an http
+ *  origin, a duplicate page id, no tab) fails `himi validate`, `render` and `push` instead of
+ *  shipping a broken app. */
+export const site = provisioning.site as SiteShellConfig;
+assertSiteShellConfig(site);
+const nav = siteNav(site);
+// The app opens on its first tab, and everything that names the home screen (`himi init`,
+// `himi render`, agent tooling) names `site_home` — so the `home` page must BE the first tab.
+if (nav.tabs[0]?.screenId !== "site_home") {
+  throw new Error('provisioning.json: the "home" page must be the first tab — list it first in site.pages');
+}
+
+export default defineApp({
+  id: "__HIMI_APP_DOTID__",
+  name: "__HIMI_APP_NAME__",
+  bundleId: "__HIMI_APP_DOTID__",
+  applicationId: "__HIMI_APP_DOTID__",
+  // Placeholders — an over-the-air app never consumes these. Leave as-is.
+  schemaPackage: "@example/__HIMI_APP_SLUG__-schema",
+  schemaPackageRange: { min: 9900, max: 9909 },
+  // Placeholders — only a local server would read these. Leave as-is.
+  ports: { devServer: 8190, web: 5390 },
+  // Visitor-only: your site's own pages handle anything a visitor does.
+  auth: { providerId: "none", config: {} },
+  telemetry: ConsoleTelemetrySink(),
+  serverUrls: {
+    screen: "http://localhost:8190/v1",
+    actions: "http://localhost:8190/v1/actions",
+    sync: "http://localhost:8190/v1/sync",
+  },
+  capabilities: [],
+  // Your brand colours paint the NATIVE chrome (tabs, drawer, splash); the site paints its pages.
+  designTokensPath: "./tokens.json",
+  // "Ready" means the first page has painted, not just the app shell — otherwise the splash
+  // fades into a blank WebView. It still dismisses after 5s on a slow link.
+  splash: {
+    enabled: true,
+    backgroundColor: "accentPrimary",
+    caption: "__HIMI_APP_NAME__",
+    minVisibleMs: 400,
+    maxHoldMs: 5000,
+    readySignal: "first_content",
+  },
+  navigation: {
+    // Bottom tabs on a phone, a sidebar on a larger screen; the drawer lists every page that is
+    // not `overflow`. At most four tabs — each keeps its page loaded while you switch.
+    navKind: "responsive",
+    scheme: "himalaya-__HIMI_APP_SLUG__",
+    deepLinkPatterns: [],
+    linkableScreens: siteLinkableScreens(site),
+    // A notification or app link carrying one of your site's URLs opens that page's tab.
+    site: siteNavConfig(site),
+    tabBar: { items: nav.tabs },
+    drawer: { items: nav.drawer },
+  },
+  entities: {},
+});

package/templates/brandy/dev/index.ts

@@ -0,0 +1,25 @@
+// Your app's screens. Each one is a page of your website — a WebView screen built from the
+// `site` block of ../provisioning.json — so this file holds no screen of its own. Change the
+// pages by changing that block, never this file.
+import { siteScreens } from "@himalaya/core";
+import config, { site } from "../config.js";
+
+const SCREENS = siteScreens(site);
+// The home screen is always the `home` page's: `site_home`. A literal on purpose — `himi init`
+// and the agent tooling read `homeScreenId` from this file as written; config.ts refuses a map
+// whose first tab is anything else, so the literal and the tab bar cannot disagree.
+
+export default {
+  config,
+  homeScreenId: "site_home",
+  screens: {
+    // A fresh copy per build: descriptors are pure functions of the site block.
+    exact: Object.fromEntries(Object.keys(SCREENS).map((id) => [id, () => structuredClone(SCREENS[id])])),
+    templated: [],
+  },
+  actions: [],
+  createStore: () => ({}),
+  // Every page is seeded, so the whole tab bar and drawer work on a cold offline start (each
+  // WebView then shows its own offline state until the network returns).
+  seed: { screens: SCREENS, data: {} },
+};

package/templates/brandy/himalaya.content.json

@@ -0,0 +1,5 @@
+{
+  "name": "__HIMI_APP_NAME__",
+  "icon": "icon.png",
+  "target": "prod"
+}

package/templates/brandy/himalaya.template.json

@@ -0,0 +1,6 @@
+{
+  "title": "Brandy — your website as an app",
+  "description": "A site shell: the customer's live Wix website as a native app. Every tab and drawer row is one of the site's own pages in a native-framed WebView, with a native tab bar, drawer, splash and brand colours; the site's header, footer and Wix ads are hidden. The page map lives in provisioning.json (`site`), and `himi site analyze --url <site> --shell brandy` derives it from the site's own menu. Start here to ship an existing website as an app today and move tabs to native screens later.",
+  "tags": ["wix", "website", "site-shell", "webview", "tabs", "drawer", "no-code", "day-zero", "consumer"],
+  "category": "consumer"
+}

package/templates/brandy/platforms.json

@@ -0,0 +1 @@
+{"macos":false}

package/templates/brandy/provisioning.json

@@ -0,0 +1,12 @@
+{
+  "site": {
+    "origin": "https://your-account.wixsite.com/your-site",
+    "kind": "wix",
+    "pages": [
+      { "id": "home", "title": "Home", "path": "/", "icon": "home" },
+      { "id": "blog", "title": "Blog", "path": "/blog", "icon": "newspaper" },
+      { "id": "contact", "title": "Contact", "path": "/contact", "icon": "mail", "placement": "drawer" }
+    ],
+    "chrome": { "hideSiteHeader": true, "hideSiteFooter": true, "hideWixAds": true }
+  }
+}

package/templates/brandy/tokens.json

@@ -0,0 +1,128 @@
+{
+  "colors": {
+    "surfacePrimary": {
+      "light": "#FFFFFF",
+      "dark": "#0D1117",
+      "highContrast": "#000000"
+    },
+    "surfaceSecondary": {
+      "light": "#F4F7F8",
+      "dark": "#161B22",
+      "highContrast": "#111111"
+    },
+    "surfaceElevated": {
+      "light": "#FFFFFF",
+      "dark": "#1D2228",
+      "highContrast": "#111111"
+    },
+    "surfaceSubtle": {
+      "light": "#F8FAF9",
+      "dark": "#121821",
+      "highContrast": "#111111"
+    },
+    "surfaceTertiary": {
+      "light": "#E9EEF0",
+      "dark": "#232A32",
+      "highContrast": "#1A1A1A"
+    },
+    "textPrimary": {
+      "light": "#1F2328",
+      "dark": "#E6EDF3",
+      "highContrast": "#FFFFFF"
+    },
+    "textSecondary": {
+      "light": "#59636E",
+      "dark": "#848D98",
+      "highContrast": "#CCCCCC"
+    },
+    "textTertiary": {
+      "light": "#7D8791",
+      "dark": "#6E7681",
+      "highContrast": "#CCCCCC"
+    },
+    "textOnAccent": {
+      "light": "#FFFFFF",
+      "dark": "#FFFFFF",
+      "highContrast": "#000000"
+    },
+    "accentPrimary": {
+      "light": "#0969DA",
+      "dark": "#1E72C7",
+      "highContrast": "#58A6FF"
+    },
+    "accentSecondary": {
+      "light": "#087F5B",
+      "dark": "#1C8968",
+      "highContrast": "#FFFFFF"
+    },
+    "accentSurface": {
+      "light": "#E2EDF8",
+      "dark": "#0C2540",
+      "highContrast": "#FFFFFF"
+    },
+    "success": {
+      "light": "#1A7F37",
+      "dark": "#3FB950",
+      "highContrast": "#3FB950"
+    },
+    "successSurface": {
+      "light": "#E9F8EC",
+      "dark": "#12331B",
+      "highContrast": "#FFFFFF"
+    },
+    "warning": {
+      "light": "#9A6700",
+      "dark": "#D29922",
+      "highContrast": "#D29922"
+    },
+    "warningSurface": {
+      "light": "#FFF5D8",
+      "dark": "#3A2C0A",
+      "highContrast": "#FFFFFF"
+    },
+    "danger": {
+      "light": "#CF222E",
+      "dark": "#F85149",
+      "highContrast": "#FF5555"
+    },
+    "dangerSurface": {
+      "light": "#FFEDEA",
+      "dark": "#3A1513",
+      "highContrast": "#FFFFFF"
+    },
+    "border": {
+      "light": "#D8DEE4",
+      "dark": "#30363D",
+      "highContrast": "#FFFFFF"
+    }
+  },
+  "spacing": {
+    "xs": 4,
+    "sm": 8,
+    "md": 12,
+    "lg": 16,
+    "xl": 24
+  },
+  "typography": {
+    "title1": {
+      "size": 28,
+      "weight": 700,
+      "line": 1.2
+    },
+    "body": {
+      "size": 16,
+      "weight": 400,
+      "line": 1.5
+    },
+    "caption": {
+      "size": 13,
+      "weight": 400,
+      "line": 1.4
+    }
+  },
+  "radius": {
+    "sm": 4,
+    "md": 8,
+    "lg": 12
+  }
+}