@fluid-app/fluid-cli-member-site 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,457 @@
-# Temporary Holding Version
+# @fluid-app/fluid-cli-member-site
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Fluid CLI plugin for member sites. Adds `fluid member-site`, which works with
+the member site API and the company member sites API: it lists, creates, pulls,
+pushes, publishes, lints and previews sites.
+
+This is not `fluid mysite`, which is an unrelated command, and not `fluid theme`.
+
+## Installation
+
+```bash
+npm install -g @fluid-app/fluid-cli @fluid-app/fluid-cli-member-site
+```
+
+Requires `@fluid-app/fluid-cli` as the core CLI.
+
+## Which login builds which site
+
+The credential follows the owner of the site:
+
+| Site owner | API                                  | Login                                   |
+| ---------- | ------------------------------------ | --------------------------------------- |
+| Member     | `/api/member/v2026-10/sites`         | The member's own login                  |
+| Company    | `/api/company/v2026-10/member-sites` | A signed-in admin who may change themes |
+
+The plugin keeps no credential of its own. It uses the login, profiles and
+`.fluidrc` of the core CLI, so `FLUID_TOKEN`, a project's `.fluidrc` profile and
+the active profile apply as they do for every other command. The API base
+follows the login: `FLUID_API_BASE` if set, else the base the stored profile was
+made for (a `.fluidrc` profile, else the active one). There is no default base,
+so a token from `FLUID_TOKEN`, or a profile with no recorded base, needs
+`FLUID_API_BASE`. With neither, the command stops with "No API base for this
+login: run `fluid login` or set FLUID_API_BASE" before it makes any request.
+
+The core CLI stores a token and does not record whose it is, so the plugin
+cannot tell a member's token from an admin's before it sends a request. Say
+which it is with `--as member` or `--as admin`, and a site of the other owner
+kind is refused before any request, with the login it needs. Without `--as`,
+the server decides, and a refusal names the login the site needs.
+
+A member who is also an admin of the same company is refused by the member API
+and builds company sites only.
+
+`fluid login` signs in admins and reps only. A member signs in to this command
+with the member's own token, set in `FLUID_TOKEN`.
+
+## Commands
+
+### `fluid member-site list`
+
+With a member login, lists the member's own sites. With an admin login, lists
+every site in the company with its owner and status. A member's site is shown
+read-only: its owner builds it.
+
+```bash
+fluid member-site list
+fluid member-site list --as member
+```
+
+Without `--as`, the company API is tried first and the member API when the
+company API refuses the login.
+
+### `fluid member-site create <handle>`
+
+Creates a site as a draft. The handle is lowercase letters, digits and single
+hyphens, at most 40 characters. The name defaults to the handle in words.
+
+```bash
+fluid member-site create rileys-shop --name "Riley's Shop"        # a member's site
+fluid member-site create fall-launch --company --as admin         # a company site
+```
+
+`--company` creates a company-owned site and needs an admin login.
+
+### `fluid member-site pull <site> [dir]`
+
+Pulls a site into a local folder. `<site>` is the site's handle or id, and
+`dir` defaults to the handle. Every text file is written at its API path, the
+pages are written to `config/pages.json`, and a binding file records where the
+folder came from.
+
+```bash
+fluid member-site pull rileys-shop --as member                  # a member's site
+fluid member-site pull fall-launch ./site --as admin            # a company site
+```
+
+```text
+rileys-shop/
+  layouts/site.liquid     sections/hero.liquid     snippets/card.liquid
+  pages/index.liquid      pages/about.liquid
+  assets/site.css         assets/site.js
+  config/settings.json    config/menus.json        config/pages.json
+  config/access.json      (only when the site declares what it uses)
+  .member-site.json
+```
+
+- The folder is the API: a path here is the path the file API uses. The home
+  page is `pages/index.liquid`.
+- `config/access.json` is the site's declaration of the viewer data it uses and
+  the actions it takes as the viewer: `{ "uses": ["member.email", "orders: read"] }`.
+  A member site has it once it has a draft declaration, and a company site never
+  does. It is a draft until the site is published.
+- `config/pages.json` holds the site's default `layout` and, for each page, its
+  `slug`, `title`, `position`, `published`, `layout` and `menu` (the menu's
+  slug). It holds no page content, which is in `pages/<slug>.liquid`. A page
+  whose content is a template the site does not own has a row there and no
+  file.
+- `.member-site.json` is the binding file. It records the site's `site_id`,
+  `handle` and `owner_kind`, the `api_base` it was pulled from, the settings
+  `lock_version`, the site's default `layout`, each page's `id`, `lock_version`
+  and row by slug (the row lets a push tell which fields you changed), and for every
+  file the `lock_version`, `updated_at` and the `version` the file list
+  reports (a binding from a pull before the API reported one has none), plus a
+  SHA-256 of the content written. It is local state and is never pushed.
+- A site holds text assets only (css, js, json, txt, html). The file list holds
+  no other file, and a listed asset that is not text is skipped and named in
+  the summary. Use images and fonts from the media library by URL.
+- A pull reads every file before it writes any, so a failed read leaves the
+  folder as it was. A file already identical on disk is left alone, so a second
+  pull of an unchanged site changes nothing.
+- A folder that is not empty and is not bound to this site is refused, and so
+  is a pull that would overwrite a file edited since the last pull. `--force`
+  writes anyway. Files that are not on the server are never removed, with one
+  exception: when the site no longer has `config/access.json` and the local copy
+  is unchanged since the last pull or push, the pull deletes it, so the next push
+  does not bring back a declaration another writer removed. An edited copy is
+  kept unless `--force` is passed.
+- A pull does not write through a symbolic link. A file or folder of the site
+  that is, or is inside, a link is refused, with or without `--force`, before
+  any file is written. Each file is written to a new file that replaces the old
+  one.
+- A member's site cannot be pulled with an admin login, because the company
+  routes refuse a member's site. With `--as admin`, or in a folder bound to a
+  member's site, that stops before any file or page request, and names the login
+  the site needs.
+
+### `fluid member-site push [dir]`
+
+Pushes the changes in a pulled folder to its site. Run it in the folder, or pass
+the folder. The folder's binding names the site and its owner kind, so a member's
+site goes through the member API and a company site through the company API, and
+a login of the other kind is refused before any request.
+
+```bash
+fluid member-site push --dry-run     # print the plan, send nothing
+fluid member-site push --as member
+fluid member-site push --publish     # push, then publish once
+```
+
+A push compares the folder with the binding and sends only what changed. A pull
+followed by a push with no edit sends nothing.
+
+Every write and delete carries the version the binding recorded for it, and the
+server refuses it with 409 if the file or page changed since. A push never
+overwrites or deletes a copy that moved on the server. A path the binding never
+saw is created with `must_not_exist`, so a file another writer created after the
+pull is not replaced.
+
+What it sends, in this order:
+
+1. `config/settings.json`, with the settings `lock_version` the binding recorded.
+   It goes first because every page write moves that version, so a settings write
+   that came after one would answer 409 to the push's own work.
+2. Each changed or new layout, section, snippet and asset, and `config/access.json`
+   (`PUT files/:path`), in path order, so the declaration goes ahead of the
+   layouts. A changed file carries its recorded `version`; a new one carries
+   `must_not_exist`. On a company site the push leaves `config/access.json`
+   alone and says so, as the server refuses the path.
+3. Each new page (`POST pages`) with its file's content, then each changed page
+   (`PATCH pages/:id`) with the changed row fields and the changed content, each
+   with the page's `lock_version`.
+4. `config/menus.json`, when it changed, with its recorded `version`. It replaces
+   every menu of the site. A menus write moves the site's version and the version
+   of every page assigned to a menu it drops, so the push reads the pages again
+   before the next step.
+5. Each page's menu assignment (`PATCH pages/:id` with `menu`), with the page's
+   re-read version. A page body never carries `menu`, so it is never sent before
+   its menu exists.
+6. Each removed page (`DELETE pages/:id?lock_version=`), then each removed
+   layout, section, snippet, asset and `config/access.json` (`DELETE files/:path?version=`;
+   removing the declaration clears its draft). Removals go
+   last, so a write that fails never leaves a menu pointing at a page that is
+   gone.
+
+After each response the binding takes the versions it returned and is saved, so
+a push that stops can be run again after a pull. A removed page or file leaves the
+binding when the server removes it. After the last write the push reads the
+settings once more to record their version, and keeps it only when the settings
+are still the ones in the folder. A second push straight after the first sends
+nothing and does not conflict with it. A push without `--publish` never
+publishes. A publish by someone else moves the version of every page, layout,
+section and snippet it publishes, so the push stops at the first of those it
+writes: pull again first.
+
+A page is removed by taking its row out of `config/pages.json` and its file out of
+the folder. A page renamed in `config/pages.json` is a new page and a removal: the
+new page is created first and the old one is deleted after it. `config/settings.json`
+and `config/menus.json` cannot be removed. If either file is missing, the push says
+so and leaves the server's copy.
+
+What it lists and does not send: a change to the site's default `layout` in
+`config/pages.json`, which is a change to the site row.
+
+What takes effect without a publish. Before the first write, the push lists the
+files and rows that are live as soon as they are written: assets (changed, new or
+removed), any removed file, `config/menus.json`, and page rows (a new page, a
+changed row field, a menu assignment, a removed page). Changes to layouts,
+sections, snippets, page content and the settings are saved as drafts, but
+removing a layout, section or snippet deletes it and its published copy at once,
+so the site stops rendering it without a publish. A push that changes none of
+these lists none.
+
+Without `--publish`, a push never calls the publish route.
+
+Everything that can be refused is refused before the first request, and every
+refusal is listed at once:
+
+- a file that is not a text asset: an asset must be css, js, json, txt or html,
+  valid UTF-8 and not empty. Use images and fonts from the media library by URL;
+- a path outside `layouts`, `sections`, `snippets`, `pages`, `assets` and
+  `config`, a path in a subfolder, a symbolic link, and a name outside lowercase
+  letters, digits, hyphens and underscores (a page's name is lowercase letters
+  and digits separated by single hyphens). Names that start with a dot are ignored;
+- a page file with no row in `config/pages.json`, and a new page row with no
+  file; a file for a page whose template the site does not own;
+- a page row removed while its file is still in the folder, and a page file
+  removed while its row is still in `config/pages.json`: a page goes with its
+  file, so remove both or neither;
+- a changed, new-to-the-binding or removed file, or changed menus, whose version
+  the binding does not hold (a binding from before the API reported versions).
+  Pull the site again first;
+- a `config/pages.json` that is not valid, a slug `index` (the home page is
+  `/`), a menu that `config/menus.json` does not define, settings that are not a
+  JSON object, and menus that are not JSON or not shaped as the API takes them
+  (an object with a `menus` array, and the required keys and types of each menu
+  and item; whether a linked page exists is left to the server);
+- new pages that do not fit in the site's 50-page limit. Removals are sent after
+  the new pages are created, so a renamed page's old page still counts. Push the
+  removals on their own first. This needs the site's current page count, so
+  `--dry-run`, which sends no request, does not check it and says so;
+- a menu link whose `url` the server's URL parser refuses: anything but a
+  well-formed `http` or `https` address with a host, as written. A space or
+  non-ASCII character in the address, or a space around it, is refused rather
+  than corrected.
+
+A `--dry-run` prints the plan, removals included, and sends no request. With
+`--publish` it also says that a publish would follow.
+
+The first stale version stops the push. It names the file or page, tells you to
+pull, lists what was already written, and sends nothing after it. A path that was
+to be created and now exists on the server is reported as created by another
+writer, and a removal the server refused is reported as not deleted. The push is
+not atomic: the API has no batch write, so what was written stays written. A stale
+settings version also follows any page another writer changed, because the
+settings version is the site's.
+
+With `--publish`, the push calls the publish route once, after the last write
+succeeded, and prints what `publish` prints (below). It is never called after a
+write failed or a change was refused, and a push with nothing to send still
+publishes. If the publish itself is refused, the pushed changes stay saved as
+drafts and the command says the site was not published.
+
+### `fluid member-site publish [dir]`
+
+Publishes the site of a pulled folder: the drafts of its layouts, sections,
+snippets, pages and settings become the live site. Run it in the folder, or pass
+the folder. A member's site is published through the member API
+(`POST sites/:id/publish`) with the member's login, and a company site through
+the company API (`POST member-sites/:id/publish`) with an admin's login, chosen
+by the binding as for `push`.
+
+```bash
+fluid member-site publish
+fluid member-site publish ./rileys-shop --as member
+```
+
+It makes one publish request and sends no file, so a local edit that was not
+pushed is not published. It prints the site's `status` and its new
+`content_version`.
+
+- A site that an admin took down cannot be published again. The command prints
+  the API's message, exits non-zero and does not retry.
+- A 409 is reported as a conflict: the site was changed while it was being
+  published, so it was not published. Run the command again.
+- A publish moves the version of every layout, section, snippet and page file it
+  publishes, of every page, and of the settings. After it succeeds the command
+  records a new version in the binding only when it can prove the publish
+  published what the folder holds, so the next push does not conflict with the
+  publish but still finds a change another writer made. A layout, section,
+  snippet or page file takes the server's version when it is the one computed
+  from the file's content in the folder. A page takes its `lock_version` when
+  that moved by exactly one. The settings take the site's `lock_version` when
+  the publish response shows the settings the folder holds and the version moved
+  by what one publish moves it. Anything else keeps its old version, the command
+  names it, and the next push stops on it and asks for a pull. A file edited in
+  the folder and not pushed is not proven either, and keeps its old version, so
+  push it before publishing. Assets and menus are not changed by a publish, and
+  keep their versions. If the versions cannot be read after the publish, the site
+  is still published, and the command says to pull before the next push.
+
+### `fluid member-site lint [dir]`
+
+Checks a site folder on disk and makes no request. It needs no login and no
+binding file, so it works on a folder that was never pulled. Run it in the
+folder, or pass the folder.
+
+```bash
+fluid member-site lint
+fluid member-site lint ./rileys-shop
+```
+
+A clean folder prints nothing and exits 0. Any error exits 1, and each finding
+names its file. Warnings are printed and do not fail the command.
+
+- Liquid in layouts, sections, snippets and pages is checked the way
+  `fluid theme lint` checks it, and its messages are the theme linter's: the
+  `{% schema %}` block and the pairing of block tags such as `{% if %}` and
+  `{% endif %}`. The theme linter's cart-code, missing-section and
+  routed-template checks are theme rules and are not run.
+- The file rules a push enforces, with the same messages: a path outside
+  `layouts`, `sections`, `snippets`, `pages`, `assets` and `config`, a name
+  outside the allowed characters, a subfolder, a symbolic link, and an asset that
+  is binary, not css, js, json, txt or html, or empty. Every file is judged, also
+  one a pull wrote.
+- `config/pages.json` must be valid, and lists at most 50 pages. The count is the
+  rows in the file, so a page with no file counts.
+- `config/menus.json` must have the shape the API takes, and each menu link
+  (`page`) must name a page that `config/pages.json` lists. A folder with no
+  `config/pages.json` lists no pages.
+- `config/access.json` must be what the file API accepts, and each problem is an
+  error: not valid JSON, a key other than `uses` or a repeated key, an entry that
+  is not a string or is listed twice, an unknown field, family or mode,
+  `session: read`, more than 64 entries, or more than 4 KiB.
+- Warnings for a site's use of viewer data. A Liquid file that reads
+  `member.<field>` is warned whatever the declaration holds, because member data is leaving
+  member-site Liquid: read it in a script with
+  `fluid.fetch("/api/member/v2026-10/me")`, which needs `profile: read`.
+- When `config/access.json` is valid, each `fluid.fetch(` call (also
+  `window.fluid.fetch(`) in a layout, section, snippet, page or `.js` asset is
+  checked against `src/lint/path-scopes.json`, a copy of the SDK's route table
+  that a test holds equal to the SDK's. The lint takes the path from a string
+  literal, or from a template literal whose `${...}` parts are whole path
+  segments (`` `/api/member/v2026-10/orders/${id}` ``), and the method from a
+  `method: "POST"` string literal in an object-literal second argument (`GET`
+  when there is none). It moves the path as `fluid.fetch` does: a Member API
+  path (`/api/member/v2026-10/...`) stays, and any other `/api/` path moves under
+  `/api/member-storefront/`. It ignores the query string. Then:
+  - a scope the declaration holds, or `session: read`, gives no finding;
+  - a scope the declaration lacks is warned, naming the scope;
+  - a route no site can reach is warned, with the reason;
+  - a call the lint cannot check is warned too, never skipped: a path or method
+    that is a variable or is computed, an interpolation that is not a whole
+    segment, a path outside `/api/`, or a path and method no route matches. Such
+    a call is refused at run time if its scope is not declared.
+
+  A folder with no `config/access.json` is not checked for calls, because a site
+  with no declaration is not limited.
+
+### `fluid member-site dev [dir]`
+
+Shows a site's draft while you edit it. It saves each change you make in a
+pulled folder as a draft and serves the draft on a local port, rendered by the
+server with the same renderer members get, not by a local one. Run it in the
+folder, or pass the folder.
+
+```bash
+fluid member-site dev
+fluid member-site dev ./rileys-shop --as member --port 9600
+fluid member-site dev --allow-production
+```
+
+- **It does not write production unless you say so.** A session saves the
+  folder when it starts and again on every change, and assets, removals, menus
+  and page rows are live as soon as they are written. So `dev` stops, before it
+  makes any request, when the login's API base is production, with a message that
+  names the base and the flag, and writes nothing. Pass `--allow-production` to
+  save to production anyway. A base that is not production keeps syncing without
+  it: a local one (`localhost`, a loopback address (any of `127.0.0.0/8`, or `::1`), `*.localhost`), a stage one
+  (`*.stage.fluid.app`) and a name under `.test`. Any other base, a custom or
+  unknown host included, is taken for production. `fluid theme dev` is
+  never pointed at a live theme either: it works on a development theme unless
+  `--theme` names another one, and this site has no development copy to use in
+  its place, so the choice is a flag.
+- **It saves drafts and never publishes.** A save is `push` without
+  `--publish`: the same plan, the same refusals, the same version on every
+  write, and the same stop at a stale version (pull, then run `dev` again). It
+  never calls the publish route. What takes effect without a publish is listed
+  before each save, as for `push`: assets, removals, menus and page rows are live
+  as soon as they are written. Run `fluid member-site publish` when the draft is
+  ready.
+- **It starts only when it can show a draft.** First it reads the site, then it
+  asks the server for the draft preview route. A server without it stops the
+  command with "Draft preview is not available on this server yet" before
+  anything is saved. It never shows the published page in its place. Then what
+  the folder holds is saved, so the page shows the folder, and a refused or stale
+  save stops the command. The folder is watched before it is read for that first
+  save, so an edit made while it runs is saved before the preview is served,
+  and none is missed.
+- **After that**, each change is saved after a short pause, and the command
+  keeps serving when a save is refused, so you can fix the file. Reload the
+  preview to see a save. There is no live reload yet.
+- **The preview** is `http://127.0.0.1:<port>` (`--port`, default 9500; `--port 0`
+  takes a free one). `/` is the home page and `/<slug>` another page, read
+  through `GET .../sites/:id/preview/pages(/:slug)` of the member API, or
+  `GET .../member-sites/:id/preview/pages(/:slug)` of the company API for a
+  company site. A text asset is at `/files/assets/<file>` (served to the
+  preview's own origin and the address bar only: see below), read through
+  `.../preview/files/*path`. A page links its assets at the published frame
+  address and its pages at the site's shell address, and neither opens a draft,
+  so the preview rewrites both to its own paths.
+- **The credential stays in the CLI.** The server listens on `127.0.0.1` only.
+  The bearer is added to the request to the API by this process, and is never in
+  a URL, a page or a header sent to the browser. Nothing the browser sends
+  (cookies, its own `Authorization`) goes to the API. A request is refused
+  unless its `Host` is the local address, its `Origin` is the preview's own, and
+  it is not a cross-site request that a page could read. A preview is served
+  with the sandbox policy the frame has, `Cache-Control: private, no-store` and
+  `Referrer-Policy: no-referrer`. The sandbox gives the page an opaque origin
+  (`Origin: null`), and so does every other sandboxed page, so the origin
+  cannot say whose request it is. The preview gives each session a random token
+  and links its assets at `/files/assets/<token>/<file>`. Only `GET` of such a
+  path, as a script or a stylesheet, is let read with CORS (a module script
+  needs it), and only then is `Access-Control-Allow-Origin: null` sent. A
+  request from an opaque origin for any other path is refused. An asset path
+  without the token (`/files/assets/<file>`, or the published frame address) is
+  served only when `Sec-Fetch-Site` is `same-origin` or `none`, so a page of
+  another site that loads it as a stylesheet or script without CORS gets
+  nothing and cannot read what the CLI's login can. The preview rewrites the
+  frame addresses in a stylesheet or script to the path with the token. The token is not the
+  credential and authorizes nothing at the API.
+- With `--as`, the login is checked as for `push`: a member's site needs a
+  member login, a company site an admin's.
+
+## Errors
+
+| API answer | What the command says                                                                             |
+| ---------- | ------------------------------------------------------------------------------------------------- |
+| 404        | Member sites are not enabled for this company or the site is not yours                            |
+| 401        | The login was not accepted, and which login the site needs                                        |
+| 403        | The API's message, and which login the site needs                                                 |
+| 409        | The site (or the named file or page) changed on the server; on a publish, a conflict to run again |
+| 422        | The API's message and each field error                                                            |
+| other      | The API's message and the request id                                                              |
+
+A 404 answers the same for a company without member sites, a missing site and
+another owner's site, so the command names the first and the last. It is never
+retried. A read that fails with 502, 503 or 504 is retried twice. A write is
+never retried.
+
+## Development
+
+```bash
+pnpm --filter @fluid-app/fluid-cli-member-site test
+pnpm --filter @fluid-app/fluid-cli-member-site typecheck
+pnpm --filter @fluid-app/fluid-cli-member-site lint
+pnpm --filter @fluid-app/fluid-cli-member-site build
+```

package/dist/index.d.mts

@@ -0,0 +1,7 @@
+import { FluidPlugin } from "@fluid-app/fluid-cli";
+
+//#region src/index.d.ts
+declare const plugin: FluidPlugin;
+//#endregion
+export { plugin as default };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;cAGM,MAAA,EAAQ,WAAA"}