@lerret/cli 0.1.8 → 0.1.10

package/src/export.js

@@ -1,8 +1,8 @@
-// `lerret export` — headless capture of a project's artboards to image files
+// `@lerret/cli export` — headless capture of a project's artboards to image files
 // (FR37, FR38).
 //
 // Renders every artboard in scope through the EXACT same `captureArtboard`
-// path the studio uses, so a `lerret export` run produces a
+// path the studio uses, so a `@lerret/cli export` run produces a
 // pixel-faithful match to what the same project produces from a click in the
 // in-studio export buttons. The mechanism is:
 //
@@ -15,7 +15,7 @@
 //      backend), then call `collectArtboards(model, scope)` to
 //      pick which artboards to capture.
 //   3. Boot a Vite dev server programmatically against the studio source plus
-//      the same `vite-plugin-lerret-project` `lerret dev` uses — exactly the
+//      the same `vite-plugin-lerret-project` `@lerret/cli dev` uses — exactly the
 //      runtime that serves the studio so the project is mounted there.
 //   4. Launch a headless Chromium through Playwright. Prefer the system
 //      `chrome`/`msedge` channel so `npx`-style invocations stay light; fall
@@ -91,7 +91,7 @@ import { lerretProjectPlugin } from './vite-plugin-lerret-project.js';
 // ─────────────────────────────────────────────────────────────────────────────
 
 /**
- * The argv shape `parseArgs` produces for `lerret export`.
+ * The argv shape `parseArgs` produces for `@lerret/cli export`.
  *
  * @typedef {object} ExportFlags
  * @property {string | undefined} pathArg
@@ -188,15 +188,15 @@ export const ARTBOARD_SELECTORS = {
 // ─────────────────────────────────────────────────────────────────────────────
 
 /**
- * Print `lerret export`'s usage banner.
+ * Print `@lerret/cli export`'s usage banner.
  *
  * @returns {void}
  */
 function printUsage() {
   const lines = [
-    'lerret export — render a project (or page/group) headlessly to image files.',
+    '@lerret/cli export — render a project (or page/group) headlessly to image files.',
     '',
-    'Usage: lerret export [path] [options]',
+    'Usage: @lerret/cli export [path] [options]',
     '',
     'Arguments:',
     '  path             Project root, or a page/group folder inside `.lerret/`.',
@@ -219,7 +219,7 @@ function printUsage() {
 }
 
 /**
- * Parse `lerret export`'s argv. A separate function so tests can verify flag
+ * Parse `@lerret/cli export`'s argv. A separate function so tests can verify flag
  * handling without booting Vite or Playwright.
  *
  * @param {string[]} argv  Argv slice after the `export` subcommand.
@@ -401,7 +401,7 @@ export async function resolveScope({ pathArg, cwd, fs = createNodeBackend() }) {
 
   // Canonicalize both ends so the path-arg comparisons below work even when
   // the user supplied a symlinked path (the classic macOS `/tmp` →
-  // `/private/tmp` gotcha that `lerret dev` also has to handle).
+  // `/private/tmp` gotcha that `@lerret/cli dev` also has to handle).
   const projectRoot = toLerretPath(realpathOrSelf(projectResolution.projectRoot));
   const lerretDir = toLerretPath(realpathOrSelf(projectResolution.lerretDir));
 
@@ -663,8 +663,15 @@ export function buildBaseFilename(artboard, extension) {
 /**
  * Compute the on-disk output path for one artboard.
  *
- * Structured (default): `<outDir>/<locationSegments>/<filename>`
- * Flat: `<outDir>/[<segments-joined-by---if-collision>]<filename>`
+ * Structured (default): `<outDir>/<page>[/<group>[/…]]/<filename>` per the PRD —
+ * the page name (derived from `artboard.pagePath`) is always present, so that
+ * a project with `landing/heroes/Card1.jsx` and `social/Banner.jsx` writes to
+ * `out/landing/heroes/Card1.png` and `out/social/Banner.png` (and assets named
+ * the same in different pages cannot collide).
+ *
+ * Flat: `<outDir>/[<segments-joined-by---if-collision>]<filename>` — flat mode
+ * never used the page prefix; we leave it as-is so existing `--flat` users see
+ * no path change.
  *
  * For flat layout, collision disambiguation needs to know whether OTHER items
  * in the same run would produce the same base filename. The caller supplies
@@ -676,7 +683,14 @@ export function buildBaseFilename(artboard, extension) {
  *   Output root, absolute and using forward slashes.
  * @param {object} args.artboard
  * @param {string[]} args.artboard.locationSegments
- *   Page/group chain — `[]` for an asset directly in a page.
+ *   Group chain — `[]` for an asset directly in a page. The page level is
+ *   derived separately from `artboard.pagePath`, not carried here (the studio's
+ *   ZIP exporter shares this field and intentionally omits the page prefix —
+ *   see packages/studio/src/export/zip.js).
+ * @param {string} [args.artboard.pagePath]
+ *   Full LerretPath of the containing page. The basename becomes the top-level
+ *   folder in structured mode. When absent (older callers / hand-crafted
+ *   artboards in tests), the page level is omitted gracefully.
  * @param {string} args.filename
  *   The base filename, already extension-suffixed.
  * @param {boolean} args.flat
@@ -699,14 +713,34 @@ export function buildOutputPath({ outDir, artboard, filename, flat, nameCount =
     return joinForward(outDir, filename);
   }
 
-  if (segments.length === 0) {
+  const pageName = pageNameFromPagePath(artboard.pagePath);
+  const structuredSegs = pageName ? [pageName, ...segments] : segments;
+
+  if (structuredSegs.length === 0) {
     return joinForward(outDir, filename);
   }
 
-  const safeSegs = segments.map(safeName);
+  const safeSegs = structuredSegs.map(safeName);
   return joinForward(outDir, ...safeSegs, filename);
 }
 
+/**
+ * Extract the page-folder name from an Artboard's `pagePath`. The path is a
+ * forward-slash LerretPath like `/proj/.lerret/landing`; the basename is the
+ * page-folder name (`landing`). Returns `null` when the input is missing or
+ * unusable so callers can fall back gracefully.
+ *
+ * @param {unknown} pagePath
+ * @returns {string | null}
+ */
+function pageNameFromPagePath(pagePath) {
+  if (typeof pagePath !== 'string' || pagePath.length === 0) return null;
+  const trimmed = pagePath.replace(/\/+$/, '');
+  const lastSlash = trimmed.lastIndexOf('/');
+  const name = lastSlash === -1 ? trimmed : trimmed.slice(lastSlash + 1);
+  return name.length > 0 ? name : null;
+}
+
 /**
  * Join path segments using forward slashes, regardless of platform. The CLI
  * normalizes every path to the contract's forward-slash form at its boundary
@@ -814,7 +848,7 @@ function readAssetVariants(asset) {
  *   1. Try `playwright-core`'s `chromium.launch({ channel: 'chrome' })`. If
  *      the user has Google Chrome / Chromium / Edge installed in a standard
  *      location, this succeeds without downloading anything — keeping `npx
- *      lerret export` light, per the architecture decision.
+ *      @lerret/cli export` light, per the architecture decision.
  *   2. If the channel launch fails, try `playwright` (the full package,
  *      which ships its bundled browser when installed). Only present when
  *      the user opts in by installing the full `playwright` package.
@@ -896,7 +930,7 @@ export async function launchHeadlessBrowser() {
 
 /**
  * Boot a Vite dev server programmatically — same plugin / fs.allow shape as
- * `lerret dev`, but with `server.open = false` and an undefined port (Vite
+ * `@lerret/cli dev`, but with `server.open = false` and an undefined port (Vite
  * picks a free one). The returned `address` is the URL to navigate to.
  *
  * @param {object} opts
@@ -940,7 +974,7 @@ export async function bootViteServer({ projectRoot, lerretDir, dataOverride, con
   // imports of `react/jsx-dev-runtime`. The user's project has no
   // `node_modules`, so those imports must resolve against the CLI's own
   // React. Without these aliases the user's assets fail to load in
-  // `dist-studio/` mode and the studio renders empty slots — `lerret dev`
+  // `dist-studio/` mode and the studio renders empty slots — `@lerret/cli dev`
   // has the same shape; we keep them in lock-step.
   const cliRequire = createRequire(import.meta.url);
   const reactAliases = [
@@ -1092,7 +1126,7 @@ function formatLocation(segments) {
 }
 
 /**
- * Run `lerret export`. Resolves the scope, boots Vite + Chromium, captures
+ * Run `@lerret/cli export`. Resolves the scope, boots Vite + Chromium, captures
  * each artboard, writes the result to disk, and returns an exit code.
  *
  * @param {string[]} argv  Argv slice after the `export` subcommand.
@@ -1110,7 +1144,7 @@ function formatLocation(segments) {
 export async function runExport(argv, deps = {}) {
   const { flags, error } = parseExportArgs(argv);
   if (error) {
-    process.stderr.write(`lerret export: ${error}\n\n`);
+    process.stderr.write(`@lerret/cli export: ${error}\n\n`);
     printUsage();
     return 1;
   }
@@ -1134,7 +1168,7 @@ export async function runExport(argv, deps = {}) {
     cwd,
   });
   if (!overrideResult.ok) {
-    process.stderr.write(`lerret export: ${overrideResult.error}\n`);
+    process.stderr.write(`@lerret/cli export: ${overrideResult.error}\n`);
     return 1;
   }
   const { dataOverride, configOverride } = overrideResult.overrides;
@@ -1142,7 +1176,7 @@ export async function runExport(argv, deps = {}) {
   // 1. Resolve project + scope.
   const scope = await resolveScope({ pathArg: flags.pathArg, cwd });
   if (!scope.found) {
-    process.stderr.write(`lerret export: ${scope.error}\n`);
+    process.stderr.write(`@lerret/cli export: ${scope.error}\n`);
     return 1;
   }
 
@@ -1151,14 +1185,14 @@ export async function runExport(argv, deps = {}) {
   try {
     baseArtboards = collectArtboards(scope.model, scope.scopePath);
   } catch (err) {
-    process.stderr.write(`lerret export: ${err && err.message ? err.message : String(err)}\n`);
+    process.stderr.write(`@lerret/cli export: ${err && err.message ? err.message : String(err)}\n`);
     return 1;
   }
 
   const expanded = expandArtboardVariants(baseArtboards);
   if (expanded.length === 0) {
     process.stderr.write(
-      `lerret export: no artboards found in scope (${scope.scopeKind}). Nothing to export.\n`,
+      `@lerret/cli export: no artboards found in scope (${scope.scopeKind}). Nothing to export.\n`,
     );
     return 1;
   }
@@ -1178,7 +1212,7 @@ export async function runExport(argv, deps = {}) {
     outDirAbs.startsWith(scope.lerretDir + '/')
   ) {
     process.stderr.write(
-      `lerret export: refusing to write into the project's \`.lerret/\` directory ` +
+      `@lerret/cli export: refusing to write into the project's \`.lerret/\` directory ` +
         `(${scope.lerretDir}). Pick an --out directory outside the project's .lerret/ tree.\n`,
     );
     return 1;
@@ -1189,7 +1223,7 @@ export async function runExport(argv, deps = {}) {
     await ensureDirFn(outDirAbs);
   } catch (err) {
     process.stderr.write(
-      `lerret export: could not create output directory ${outDirAbs}: ` +
+      `@lerret/cli export: could not create output directory ${outDirAbs}: ` +
         `${err && err.message ? err.message : String(err)}\n`,
     );
     return 1;
@@ -1206,10 +1240,10 @@ export async function runExport(argv, deps = {}) {
           ? ' [--config override active]'
           : '';
   process.stdout.write(
-    `lerret export: project ${scope.projectRoot}\n` +
-      `lerret export: scope ${scope.scopeKind}${scope.scopePath ? ` (${scope.scopePath})` : ''}\n` +
-      `lerret export: ${expanded.length} artboard${expanded.length === 1 ? '' : 's'} to capture (${flags.format})${overrideNote}\n` +
-      `lerret export: writing to ${outDirAbs}${flags.flat ? ' (flat layout)' : ''}\n`,
+    `@lerret/cli export: project ${scope.projectRoot}\n` +
+      `@lerret/cli export: scope ${scope.scopeKind}${scope.scopePath ? ` (${scope.scopePath})` : ''}\n` +
+      `@lerret/cli export: ${expanded.length} artboard${expanded.length === 1 ? '' : 's'} to capture (${flags.format})${overrideNote}\n` +
+      `@lerret/cli export: writing to ${outDirAbs}${flags.flat ? ' (flat layout)' : ''}\n`,
   );
 
   const bootServer = deps.bootServer || bootViteServer;
@@ -1235,7 +1269,7 @@ export async function runExport(argv, deps = {}) {
       url = booted.url;
     } catch (err) {
       process.stderr.write(
-        `lerret export: Vite dev server failed to start: ` +
+        `@lerret/cli export: Vite dev server failed to start: ` +
           `${err && err.message ? err.message : String(err)}\n`,
       );
       return 1;
@@ -1244,10 +1278,10 @@ export async function runExport(argv, deps = {}) {
     try {
       const launched = await launchBrowser();
       browser = launched.browser;
-      process.stdout.write(`lerret export: ${launched.launchedVia}\n`);
+      process.stdout.write(`@lerret/cli export: ${launched.launchedVia}\n`);
     } catch (err) {
       process.stderr.write(
-        `lerret export: ${err && err.message ? err.message : String(err)}\n`,
+        `@lerret/cli export: ${err && err.message ? err.message : String(err)}\n`,
       );
       return 1;
     }
@@ -1270,7 +1304,7 @@ export async function runExport(argv, deps = {}) {
       await page.waitForSelector(firstSelector, { state: 'attached', timeout: 30000 });
     } catch (err) {
       process.stderr.write(
-        `lerret export: studio did not render any artboards within 30s ` +
+        `@lerret/cli export: studio did not render any artboards within 30s ` +
           `(${err && err.message ? err.message : String(err)}). The project may be empty or failed to load.\n`,
       );
       return 1;
@@ -1359,16 +1393,16 @@ export async function runExport(argv, deps = {}) {
     // 7. Summary.
     const summaryLines = [
       '',
-      `lerret export: wrote ${writtenCount} of ${expanded.length} image${expanded.length === 1 ? '' : 's'} to ${outDirAbs}`,
+      `@lerret/cli export: wrote ${writtenCount} of ${expanded.length} image${expanded.length === 1 ? '' : 's'} to ${outDirAbs}`,
     ];
     if (failures.length > 0) {
       summaryLines.push(
-        `lerret export: ${failures.length} artboard${failures.length === 1 ? '' : 's'} failed (see messages above)`,
+        `@lerret/cli export: ${failures.length} artboard${failures.length === 1 ? '' : 's'} failed (see messages above)`,
       );
     }
     if (allUnembeddedFonts.size > 0) {
       summaryLines.push(
-        `lerret export: fonts not embedded: ${[...allUnembeddedFonts].sort().join(', ')}`,
+        `@lerret/cli export: fonts not embedded: ${[...allUnembeddedFonts].sort().join(', ')}`,
       );
     }
     process.stdout.write(summaryLines.join('\n') + '\n');

package/src/fs/node-backend.js

@@ -325,7 +325,7 @@ export { NODE_CAPABILITIES };
 // realpath helper — CLI-internal, NOT part of the FilesystemAccess contract
 // ---------------------------------------------------------------------------
 //
-// `lerret dev` configures Vite's `server.fs.allow`, which Vite enforces by
+// `@lerret/cli dev` configures Vite's `server.fs.allow`, which Vite enforces by
 // comparing against the *real* (symlink-resolved) path of each request. On
 // macOS `/tmp` is a symlink to `/private/tmp`, so an `--folder /tmp/foo`
 // argument must be resolved to `/private/tmp/foo` before being added to
@@ -378,7 +378,7 @@ export function pathExists(path) {
 /**
  * Recursively create a directory (no-op if it already exists). Used by
  * subsystems that need to materialize an output tree on disk — the bulk
- * `lerret export` writer lands captured images under a user-
+ * `@lerret/cli export` writer lands captured images under a user-
  * specified `--out` directory and needs to mkdir intermediate folders for the
  * structured layout. Kept in this file so the `fs` ban for the rest of the
  * codebase is preserved (this is the sanctioned escape).
@@ -393,7 +393,7 @@ export async function ensureDir(lerretPath) {
 
 /**
  * Canonicalize the deepest existing prefix of a path, then re-attach the
- * still-virtual trailing components. Used by `lerret export` to compare a
+ * still-virtual trailing components. Used by `@lerret/cli export` to compare a
  * user-supplied `--out` directory against the project's `.lerret/` path even
  * when `--out` does not yet exist on disk.
  *

package/src/lerret.js

@@ -5,8 +5,8 @@
 // node's built-in `util.parseArgs` — the architecture's explicit choice, no
 // heavy CLI framework. Recognized subcommands:
 //
-//   lerret dev    [--port <n>] [--folder <path>] [--open | --no-open]
-//   lerret export [path] [--format png|jpg] [--out <dir>] [--flat]
+//   @lerret/cli dev    [--port <n>] [--folder <path>] [--open | --no-open]
+//   @lerret/cli export [path] [--format png|jpg] [--out <dir>] [--flat]
 //
 // Adding a new subcommand is the act of importing one more module and adding
 // an entry to the `SUBCOMMANDS` table below — the usage banner is derived
@@ -53,16 +53,16 @@ const SUBCOMMANDS = {
  */
 function printUsage() {
   const lines = [
-    'lerret — the design-canvas CLI',
+    '@lerret/cli — the design-canvas CLI',
     '',
-    'Usage: lerret <command> [options]',
+    'Usage: @lerret/cli <command> [options]',
     '',
     'Commands:',
     ...Object.entries(SUBCOMMANDS).map(
       ([name, { describe }]) => `  ${name.padEnd(8)} ${describe}`,
     ),
     '',
-    'Run `lerret <command> --help` for command-specific options.',
+    'Run `@lerret/cli <command> --help` for command-specific options.',
   ];
   process.stdout.write(lines.join('\n') + '\n');
 }
@@ -91,7 +91,7 @@ export async function main(argv = process.argv.slice(2)) {
   if (!handler) {
     // An unknown subcommand is a usage error — print the banner so the user
     // can see what is valid, then exit non-zero.
-    process.stderr.write(`lerret: unknown command "${command}"\n\n`);
+    process.stderr.write(`@lerret/cli: unknown command "${command}"\n\n`);
     printUsage();
     return 1;
   }
@@ -102,7 +102,7 @@ export async function main(argv = process.argv.slice(2)) {
   } catch (err) {
     // A genuine runtime failure inside a subcommand — surface a short error and
     // exit non-zero. The subcommand owns its own error UX otherwise.
-    process.stderr.write(`lerret ${command}: ${err && err.message ? err.message : String(err)}\n`);
+    process.stderr.write(`@lerret/cli ${command}: ${err && err.message ? err.message : String(err)}\n`);
     return 1;
   }
 }

package/src/vite-plugin-lerret-project.js

@@ -1,8 +1,8 @@
 // vite-plugin-lerret-project.js — the Vite plugin that exposes the user's
-// `.lerret/` project to the studio in `lerret dev` mode.
+// `.lerret/` project to the studio in `@lerret/cli dev` mode.
 //
 // ── Why a Vite plugin ──────────────────────────────────────────────────────
-// `lerret dev` boots a Node-side Vite dev server pointed at the studio source
+// `@lerret/cli dev` boots a Node-side Vite dev server pointed at the studio source
 // (`packages/studio/`). The studio is a normal Vite-served SPA. To swap from
 // the studio's standalone fixture project to a real user folder we need four
 // things, and a Vite plugin owns all of them in one place:
@@ -71,7 +71,7 @@ import { startWatcher } from './watcher.js';
 
 // ── Cascade-override helpers ─────────────────────────────────────────────────
 //
-// When `--config` is supplied to `lerret export`, its value is deep-merged
+// When `--config` is supplied to `@lerret/cli export`, its value is deep-merged
 // into every entry of the cascade (the `cascadeEntries` the plugin exposes
 // via the virtual module). We replicate the same deep-merge semantics that
 // `computeCascadedConfig`'s internal `deepMerge` uses:
@@ -314,12 +314,12 @@ export function checkWritePath(requestPath, lerretDir) {
 }
 
 /**
- * Create the `lerret dev` / `lerret export` Vite plugin.
+ * Create the `@lerret/cli dev` / `@lerret/cli export` Vite plugin.
  *
  * @param {object} opts
  * @param {string | null} opts.projectRoot
  *   The user's project root — the folder that directly contains `.lerret/`,
- *   or `null` if `lerret dev` was invoked outside any project (no-folder
+ *   or `null` if `@lerret/cli dev` was invoked outside any project (no-folder
  *   fallback).
  * @param {string | null} opts.lerretDir
  *   The user's `.lerret/` directory path, or `null` matching `projectRoot`.
@@ -433,7 +433,7 @@ export function lerretProjectPlugin({ projectRoot, lerretDir, dataOverride, conf
     /**
      * Inject a tiny inline script into the served `index.html` so the
      * studio's `main.jsx` can synchronously detect that it is running
-     * under `lerret dev`. Without this signal the studio would have to
+     * under `@lerret/cli dev`. Without this signal the studio would have to
      * try a dynamic import of `virtual:lerret-project` — which the
      * browser refuses with a CORS error (the bare specifier isn't a URL).
      *