@simplysf/simply-utam 0.2.0 → 0.3.1

package/README.md

@@ -16,12 +16,135 @@ Requires Node.js 22 or later.
 
 ## Commands
 
-- `simply-utam init`: Scaffolds starter UTAM configs (`generator.config.json`, `utam.config.json`, `wdio.conf.mjs`, `.utam/namespace-map.json`), non-destructively injects standard Wireit tasks into `package.json`, and adds any missing UTAM rules to `.forceignore` under a `# Ignore UTAM` comment so LWC bundles that contain UTAM files deploy successfully. Existing lines are never changed; new rules go inside the `# -- START CUSTOMIZATION` / `# -- END CUSTOMIZATION` region when one exists (`--forceignore-region-start` / `--forceignore-region-end` to change the markers, `--no-forceignore` to skip). The UTAM namespace is the `package.json` name, scope included, so page objects can import each other by the package's own name (`--app-name` to override). It also adds `"./pageObjects/*": "./pageObjects/*.js"` to `package.json` `exports`, which those imports resolve through; an existing entry is never changed.
+- `simply-utam init`: Scaffolds starter UTAM configs (`generator.config.json`, `utam.config.json`, `wdio.conf.mjs`, `.utam/namespace-map.json`) and the DOM snapshot capture step (`step_definitions/dom-snapshot.steps.mjs`) in the UTAM test folder, adds `.utam/snapshots/` to `.gitignore` (`--no-gitignore` to skip), non-destructively injects standard Wireit tasks into `package.json`, and adds any missing UTAM rules to `.forceignore` under a `# Ignore UTAM` comment so LWC bundles that contain UTAM files deploy successfully. Existing lines are never changed; new rules go inside the `# -- START CUSTOMIZATION` / `# -- END CUSTOMIZATION` region when one exists (`--forceignore-region-start` / `--forceignore-region-end` to change the markers, `--no-forceignore` to skip). The UTAM namespace is the `package.json` name, scope included, so page objects can import each other by the package's own name (`--app-name` to override). It also adds `"./pageObjects/*": "./pageObjects/*.js"` to `package.json` `exports`, which those imports resolve through; an existing entry is never changed.
 - `simply-utam rules`: Scans LWC component definitions and generates or updates UTAM `.rules.json` files for root components.
 - `simply-utam overrides`: Deeply merges custom element assertions, wait conditions, and visibility rules from `*.utam-overrides.json` into generated `*.utam.json` files while preserving file indentation.
 - `simply-utam rewrite`: Rewrites namespace prefixes across compiled `*.utam.json` files according to `.utam/namespace-map.json`.
 - `simply-utam steps`: Statically analyzes Gherkin `.feature` files, compiles existing step expressions, detects true undefined steps, and appends formatted Cucumber expressions into target step files.
 - `simply-utam build`: Convenience runner executing all compilation and transformation stages sequentially (`rules -> utam-generate -> overrides -> rewrite -> utam`).
+- `simply-utam snapshot find`: Finds nodes in a DOM snapshot by `--text`, `--attr`, `--tag` or `--class`, visible matches first; or tests a CSS selector with `--css` as UTAM's `findElement` runs it, in the document or `--within` a node's light DOM or, with `--shadow`, its shadow root. `--all` lists hidden matches in full.
+- `simply-utam snapshot path`: Shows the custom elements from the document down to a node (`--node` or `--text`), with each shadow crossing, the page object for each element, the route to it from the page object above, and warnings for a root selector that loads a hidden copy or an element declared in the wrong scope. Exits 1 when `--text` doesn't find exactly one visible node.
+- `simply-utam snapshot tree`: Prints the tree under a node (`--node`, `--depth`), shadow root first, then light DOM.
+- `simply-utam snapshot node`: Shows one node in full, or with `--ancestors`, its ancestors nearest first.
+- Every `snapshot` command but `lookup` reads `.utam/snapshots/latest.json` (or `--file`) and prints a header naming it, with a failed step's error and, for UTAM's not-found error, the `find --css` that repeats its search. All take `--json`, `--limit` and `--project-dir`, and exit 2 on bad input.
+- `simply-utam snapshot console snippet`: Prints the snippet to paste into a browser's DevTools console to capture a DOM snapshot of any page, with no test run, or copies it with `--copy`. `--mask` (`structure`, `labels`, `aria` or `full`) fixes the mask mode in the snippet. The snippet copies the masked snapshot to the clipboard, or downloads it where the console's `copy` isn't available.
+- `simply-utam snapshot console import`: Saves the snapshot the snippet copied (or `--file <path>`, `--file -` for standard input) to `.utam/snapshots/manual/` and `latest.json`, with an optional `--label`, and prints its header. Exits 2 on bad input.
+- `simply-utam snapshot lookup`: Shows the page objects for a custom element tag or a page object name, from the project's own page objects and the page-object packages its namespaces map to (`salesforce-pageobjects` through the scaffolded `lightning` namespace): import path, methods and what they do, and public and private elements with their light or shadow scope. `--search <words>` finds page objects by name, tag or description. Needs no snapshot. Takes `--json`, `--limit` and `--project-dir`. See [design 0003](../../docs/design/0003-dom-snapshots.md).
+
+## DOM snapshots in an existing project
+
+`init` writes `wdio.conf.mjs` only when it doesn't exist yet, so an existing project's configuration
+doesn't capture DOM snapshots until you add the hooks. Merge these into your `config`, keeping any
+hooks you already have (`afterStep` most likely also takes a screenshot):
+
+```js
+import allureReporter from '@wdio/allure-reporter';
+
+// Imported here rather than with a static import, so a project whose @simplysf/simply-utam predates
+// DOM snapshots still loads this config: the snapshot hooks then skip, and onPrepare says to upgrade.
+const snapshots = await loadSnapshotApi();
+
+async function loadSnapshotApi() {
+  const api = await import('@simplysf/simply-utam');
+  const names = [
+    'captureDomSnapshot',
+    'pruneDomSnapshots',
+    'serializeDomSnapshot',
+    'snapshotRunId',
+    'writeDomSnapshot',
+  ];
+  return names.every((name) => typeof api[name] === 'function') ? api : undefined;
+}
+
+export const config = {
+  // …
+  onPrepare: async function () {
+    if (!snapshots) {
+      console.warn(
+        'The installed @simplysf/simply-utam has no DOM snapshots, so none are captured. Upgrade it in package.json to capture them.',
+      );
+      return;
+    }
+    // One DOM snapshot folder per test run, shared by every worker.
+    process.env.UTAM_SNAPSHOT_RUN_ID ??= snapshots.snapshotRunId();
+  },
+  onComplete: async function () {
+    if (!snapshots) return;
+    // Keep the last 10 runs, this one included. Housekeeping must never cost the run: on Windows a
+    // locked old run folder can't be deleted.
+    try {
+      await snapshots.pruneDomSnapshots({ keepRuns: 10 });
+    } catch (pruneError) {
+      console.warn(`Old DOM snapshot runs not pruned: ${pruneError?.message ?? pruneError}`);
+    }
+  },
+  before: async function () {
+    if (!snapshots) return;
+    // browser.domSnapshot('label') captures the page from the REPL during browser.debug().
+    browser.addCommand('domSnapshot', async (label) => {
+      const snapshot = await snapshots.captureDomSnapshot({ trigger: 'manual', label });
+      return snapshot ? snapshots.writeDomSnapshot(snapshot) : undefined;
+    });
+  },
+  afterStep: async function (step, scenario, { error }) {
+    if (error) {
+      // Capture the DOM snapshot first, before anything else changes the page.
+      const snapshot = await snapshots?.captureDomSnapshot({
+        trigger: 'failure',
+        scenario: scenario.name,
+        step: step.text,
+        error,
+      });
+      if (snapshot) {
+        // Saving and attaching each get their own try: neither failing may cost the other, or the
+        // screenshot below.
+        try {
+          console.log(`DOM snapshot written to ${await snapshots.writeDomSnapshot(snapshot)}`);
+        } catch (writeError) {
+          console.warn(`DOM snapshot not saved: ${writeError?.message ?? writeError}`);
+        }
+        try {
+          allureReporter.addAttachment(
+            'dom-snapshot.json',
+            snapshots.serializeDomSnapshot(snapshot),
+            'application/json',
+          );
+        } catch (attachError) {
+          console.warn(`DOM snapshot not attached to the Allure report: ${attachError?.message ?? attachError}`);
+        }
+      }
+      await browser.takeScreenshot();
+    }
+  },
+};
+```
+
+Also set `cucumberOpts.timeout` above `waitforTimeout` (the scaffold adds 30 seconds), so a step that
+waits for a missing element fails with UTAM's error, which names the locator, rather than only
+Cucumber's timeout. `init` adds the capture step to an existing project's UTAM test folder, since
+it's a new file. For the guide, install the [`utam-dom-snapshots` skill](#agent-skills).
+
+## Agent skills
+
+The package ships agent skills for working with simply-utam in your project: guides that a coding
+agent (or a person) follows to use its commands. Each is a folder under `skills/`, with a `SKILL.md`
+whose frontmatter tells an agent when to load it. None is installed for you; add the ones you want.
+
+| Skill                                                      | Use it when                                                                                                                             |
+| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| [`utam-dom-snapshots`](skills/utam-dom-snapshots/SKILL.md) | Writing or fixing a UTAM step definition, page object or selector: capturing DOM snapshots, querying them, and looking up page objects. |
+
+Link a skill into your agent's skills folder, so it stays in step with the installed version of
+simply-utam. For Claude Code, from the project folder:
+
+```bash
+mkdir -p .claude/skills
+ln -s ../../node_modules/@simplysf/simply-utam/skills/utam-dom-snapshots .claude/skills/utam-dom-snapshots
+```
+
+Or copy the folder instead, to edit it; a copy doesn't change when you upgrade simply-utam, so
+copy it again after an upgrade. Other agents read skills from their own folders; link or copy the
+skill there the same way.
 
 ## Usage & Wireit Integration
 

package/lib/clipboard.d.ts

@@ -0,0 +1,31 @@
+/** What a command printed, and how it exited. */
+export type CommandResult = {
+    code: number | null;
+    stdout: string;
+};
+/** Runs a command with `input` on its standard input. Rejects when the command can't start. */
+export type CommandRunner = (command: string, args: string[], input?: string) => Promise<CommandResult>;
+/** The system clipboard, as text. */
+export type Clipboard = {
+    read(): Promise<string>;
+    write(text: string): Promise<void>;
+};
+/**
+ * Runs a command, collecting its standard output when it's given no input. A command given input is
+ * writing, and its output is ignored: `xclip` and `wl-copy` leave a process behind to serve the
+ * clipboard, and one holding the output pipe would keep `close` from firing until the clipboard changes.
+ */
+export declare const runCommand: CommandRunner;
+/** Thrown when no clipboard tool for this platform works. */
+export declare class ClipboardUnavailableError extends Error {
+}
+/**
+ * The system clipboard, through the platform's own tools: `pbcopy` and `pbpaste` on macOS, PowerShell
+ * on Windows, and `wl-copy`, `xclip` or `xsel` on Linux.
+ *
+ * @param options The platform (the current one by default) and how commands are run, for tests.
+ */
+export declare function systemClipboard(options?: {
+    platform?: NodeJS.Platform;
+    run?: CommandRunner;
+}): Clipboard;

package/lib/clipboard.js

@@ -0,0 +1,98 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { spawn } from 'node:child_process';
+// Windows PowerShell writes the console's code page unless told otherwise.
+const POWERSHELL = ['-NoProfile', '-NonInteractive', '-Command'];
+const UTF8 = '[Console]::OutputEncoding = [Text.Encoding]::UTF8; [Console]::InputEncoding = [Text.Encoding]::UTF8; ';
+const READ_TOOLS = {
+    darwin: [{ command: 'pbpaste', args: [] }],
+    win32: [{ command: 'powershell', args: [...POWERSHELL, `${UTF8}Get-Clipboard -Raw`] }],
+    linux: [
+        { command: 'wl-paste', args: ['--no-newline'] },
+        { command: 'xclip', args: ['-selection', 'clipboard', '-o'] },
+        { command: 'xsel', args: ['--clipboard', '--output'] },
+    ],
+};
+const WRITE_TOOLS = {
+    darwin: [{ command: 'pbcopy', args: [] }],
+    win32: [{ command: 'powershell', args: [...POWERSHELL, `${UTF8}Set-Clipboard -Value ([Console]::In.ReadToEnd())`] }],
+    linux: [
+        { command: 'wl-copy', args: [] },
+        { command: 'xclip', args: ['-selection', 'clipboard'] },
+        { command: 'xsel', args: ['--clipboard', '--input'] },
+    ],
+};
+/**
+ * Runs a command, collecting its standard output when it's given no input. A command given input is
+ * writing, and its output is ignored: `xclip` and `wl-copy` leave a process behind to serve the
+ * clipboard, and one holding the output pipe would keep `close` from firing until the clipboard changes.
+ */
+export const runCommand = (command, args, input) => new Promise((resolve, reject) => {
+    const reading = input === undefined;
+    const child = spawn(command, args, { stdio: ['pipe', reading ? 'pipe' : 'ignore', 'ignore'], windowsHide: true });
+    const chunks = [];
+    child.stdout?.on('data', (chunk) => chunks.push(chunk));
+    child.on('error', reject);
+    child.on('close', (code) => resolve({ code, stdout: Buffer.concat(chunks).toString('utf8') }));
+    // A tool that exits without reading its input closes the pipe; `close` still reports how it exited.
+    child.stdin?.on('error', () => undefined);
+    child.stdin?.end(input ?? '');
+});
+/** Thrown when no clipboard tool for this platform works. */
+export class ClipboardUnavailableError extends Error {
+}
+async function firstWorking(tools, run, input) {
+    // Tools that ran but exited with an error, rather than not being installed.
+    const failed = [];
+    for (const tool of tools) {
+        try {
+            // Tools are tried one at a time: the first that works is the one to use.
+            // eslint-disable-next-line no-await-in-loop
+            const result = await run(tool.command, tool.args, input);
+            if (result.code === 0)
+                return result.stdout;
+            failed.push(tool.command);
+        }
+        catch {
+            // Not installed; try the next one.
+        }
+    }
+    if (tools.length === 0)
+        throw new ClipboardUnavailableError('no clipboard tool for this platform');
+    const tried = tools.map((tool) => tool.command).join(', ');
+    // Paste tools such as wl-paste and xclip exit with an error when the clipboard holds no text.
+    const ranButFailed = failed.length === 0
+        ? ''
+        : `; ${failed.join(', ')} ran but failed${input === undefined ? ', as it does when the clipboard is empty' : ''}`;
+    throw new ClipboardUnavailableError(`no clipboard tool worked (tried ${tried})${ranButFailed}`);
+}
+/**
+ * The system clipboard, through the platform's own tools: `pbcopy` and `pbpaste` on macOS, PowerShell
+ * on Windows, and `wl-copy`, `xclip` or `xsel` on Linux.
+ *
+ * @param options The platform (the current one by default) and how commands are run, for tests.
+ */
+export function systemClipboard(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const run = options.run ?? runCommand;
+    return {
+        read: () => firstWorking(READ_TOOLS[platform] ?? [], run),
+        async write(text) {
+            await firstWorking(WRITE_TOOLS[platform] ?? [], run, text);
+        },
+    };
+}
+//# sourceMappingURL=clipboard.js.map

package/lib/clipboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clipboard.js","sourceRoot":"","sources":["../src/clipboard.ts"],"names":[],"mappings":"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"}

package/lib/commands/init.d.ts

@@ -17,8 +17,9 @@ export default class Init extends Command {
         forceignore: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'forceignore-region-start': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'forceignore-region-end': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        gitignore: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<ScaffoldResult>;
-    private logForceignore;
+    private logIgnoreFile;
 }

package/lib/commands/init.js

@@ -16,12 +16,13 @@
 import * as path from 'node:path';
 import { Command, Flags } from '@oclif/core';
 import { DEFAULT_FORCEIGNORE_REGION, scaffoldProject, } from '@simplysf/simply-utam-core';
+const SNAPSHOT_HOOKS_DOCS = 'https://github.com/SimplySF/simply-utam/tree/main/packages/simply-utam#dom-snapshots-in-an-existing-project';
 /**
  * CLI command to scaffold SimplyUTAM configurations, Wireit tasks, and namespace maps.
  */
 export default class Init extends Command {
     static summary = 'Scaffold UTAM configurations, Wireit tasks, and namespace maps in a Salesforce project.';
-    static description = 'Inspects the target project, generates generator.config.json, utam.config.json, wdio.conf.mjs, and .utam/namespace-map.json, non-destructively injects standard Wireit tasks into package.json, and adds any missing UTAM rules to .forceignore under a "# Ignore UTAM" comment without changing existing lines.';
+    static description = 'Inspects the target project, generates generator.config.json, utam.config.json, wdio.conf.mjs, and .utam/namespace-map.json, adds the DOM snapshot capture step to the UTAM test folder, non-destructively injects standard Wireit tasks into package.json, and adds any missing UTAM rules to .forceignore and .gitignore under a "# Ignore UTAM" comment without changing existing lines.';
     static examples = [
         '<%= config.bin %> <%= command.id %>',
         '<%= config.bin %> <%= command.id %> --source-dir force-app --app-name my-app',
@@ -65,6 +66,11 @@ export default class Init extends Command {
             summary: 'Exact line that ends the .forceignore customization region.',
             default: DEFAULT_FORCEIGNORE_REGION.end,
         }),
+        gitignore: Flags.boolean({
+            summary: 'Add .utam/snapshots/ to .gitignore, so DOM snapshots stay out of git.',
+            default: true,
+            allowNo: true,
+        }),
         verbose: Flags.boolean({
             char: 'v',
             summary: 'Enable detailed output.',
@@ -83,6 +89,7 @@ export default class Init extends Command {
             forceignore: flags.forceignore,
             forceignoreRegionStart: flags['forceignore-region-start'],
             forceignoreRegionEnd: flags['forceignore-region-end'],
+            gitignore: flags.gitignore,
         });
         if (flags['dry-run']) {
             this.log(`[dry-run] Project scaffolding preview for: ${resolvedTarget}`);
@@ -109,7 +116,14 @@ export default class Init extends Command {
             }
         }
         if (result.forceignore) {
-            this.logForceignore(result.forceignore, flags['dry-run']);
+            this.logIgnoreFile(result.forceignore, flags['dry-run'], 'UTAM artifacts');
+        }
+        if (result.gitignore) {
+            this.logIgnoreFile(result.gitignore, flags['dry-run'], 'DOM snapshots');
+        }
+        if (result.snapshotHooksMissing) {
+            this.log('\nwdio.conf.mjs already exists, so it was kept, and it does not capture DOM snapshots on failure. ' +
+                `To add that, copy the snapshot API loader and the onPrepare, before, afterStep and onComplete hooks from ${SNAPSHOT_HOOKS_DOCS}`);
         }
         const pageObjectExports = result.pageObjectExports;
         if (pageObjectExports?.action === 'added') {
@@ -129,26 +143,26 @@ export default class Init extends Command {
         }
         return result;
     }
-    logForceignore(forceignore, dryRun) {
+    logIgnoreFile(file, dryRun, covers) {
         const where = {
             block: 'under the existing "# Ignore UTAM" comment',
             region: 'inside the customization region',
             end: 'at the end of the file',
         };
-        const created = forceignore.action === 'created';
-        if (forceignore.addedPatterns.length > 0) {
+        const created = file.action === 'created';
+        if (file.addedPatterns.length > 0) {
             const verb = dryRun ? (created ? 'Would create' : 'Would update') : created ? 'Created' : 'Updated';
-            const placement = forceignore.placement && !created ? ` (${where[forceignore.placement]})` : '';
-            this.log(`${verb} ${forceignore.path}: added ${forceignore.addedPatterns.join(', ')}${placement}`);
+            const placement = file.placement && !created ? ` (${where[file.placement]})` : '';
+            this.log(`${verb} ${file.path}: added ${file.addedPatterns.join(', ')}${placement}`);
         }
-        else if (forceignore.action === 'unchanged') {
-            this.log(`${forceignore.path} already covers UTAM artifacts.`);
+        else if (file.action === 'unchanged') {
+            this.log(`${file.path} already covers ${covers}.`);
         }
-        else if (forceignore.action === 'skipped') {
-            this.log(`Skipped ${forceignore.path}: no ${forceignore.path} or sfdx-project.json found. ` +
+        else if (file.action === 'skipped') {
+            this.log(`Skipped ${file.path}: no ${file.path} or sfdx-project.json found. ` +
                 'Point --project-dir at the folder that contains sfdx-project.json, or add the UTAM rules yourself.');
         }
-        for (const warning of forceignore.warnings) {
+        for (const warning of file.warnings) {
             this.warn(warning);
         }
     }

package/lib/commands/init.js.map

@@ -1 +1 @@
-{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,0BAA0B,EAC1B,eAAe,GAGhB,MAAM,4BAA4B,CAAC;AAEpC;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,IAAK,SAAQ,OAAO;IAChC,MAAM,CAAU,OAAO,GAC5B,yFAAyF,CAAC;IAErF,MAAM,CAAU,WAAW,GAChC,kTAAkT,CAAC;IAE9S,MAAM,CAAU,QAAQ,GAAG;QAChC,qCAAqC;QACrC,8EAA8E;QAC9E,+CAA+C;QAC/C,uHAAuH;KACxH,CAAC;IAEK,MAAM,CAAU,cAAc,GAAG,IAAI,CAAC;IAEtC,MAAM,CAAU,KAAK,GAAG;QAC7B,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC;YAC1B,OAAO,EAAE,yCAAyC;YAClD,OAAO,EAAE,GAAG;SACb,CAAC;QACF,YAAY,EAAE,KAAK,CAAC,MAAM,CAAC;YACzB,IAAI,EAAE,GAAG;YACT,OAAO,EAAE,wFAAwF;SAClG,CAAC;QACF,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC;YACvB,IAAI,EAAE,GAAG;YACT,OAAO,EAAE,uFAAuF;SACjG,CAAC;QACF,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC;YACnB,IAAI,EAAE,GAAG;YACT,OAAO,EAAE,yCAAyC;YAClD,OAAO,EAAE,KAAK;SACf,CAAC;QACF,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC;YACvB,IAAI,EAAE,GAAG;YACT,OAAO,EAAE,gDAAgD;YACzD,OAAO,EAAE,KAAK;SACf,CAAC;QACF,WAAW,EAAE,KAAK,CAAC,OAAO,CAAC;YACzB,OAAO,EAAE,yCAAyC;YAClD,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,IAAI;SACd,CAAC;QACF,0BAA0B,EAAE,KAAK,CAAC,MAAM,CAAC;YACvC,OAAO,EAAE,+DAA+D;YACxE,OAAO,EAAE,0BAA0B,CAAC,KAAK;SAC1C,CAAC;QACF,wBAAwB,EAAE,KAAK,CAAC,MAAM,CAAC;YACrC,OAAO,EAAE,6DAA6D;YACtE,OAAO,EAAE,0BAA0B,CAAC,GAAG;SACxC,CAAC;QACF,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC;YACrB,IAAI,EAAE,GAAG;YACT,OAAO,EAAE,yBAAyB;YAClC,OAAO,EAAE,KAAK;SACf,CAAC;KACH,CAAC;IAEK,KAAK,CAAC,GAAG;QACd,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACzC,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC;QAE1D,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC;YACnC,UAAU,EAAE,KAAK,CAAC,aAAa,CAAC;YAChC,SAAS,EAAE,KAAK,CAAC,YAAY,CAAC;YAC9B,OAAO,EAAE,KAAK,CAAC,UAAU,CAAC;YAC1B,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,MAAM,EAAE,KAAK,CAAC,SAAS,CAAC;YACxB,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,sBAAsB,EAAE,KAAK,CAAC,0BAA0B,CAAC;YACzD,oBAAoB,EAAE,KAAK,CAAC,wBAAwB,CAAC;SACtD,CAAC,CAAC;QAEH,IAAI,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;YACrB,IAAI,CAAC,GAAG,CAAC,8CAA8C,cAAc,EAAE,CAAC,CAAC;YACzE,IAAI,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACnC,IAAI,CAAC,GAAG,CAAC,gCAAgC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC7E,CAAC;YACD,IAAI,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACnC,IAAI,CAAC,GAAG,CACN,0EAA0E,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC3G,CAAC;YACJ,CAAC;YACD,IAAI,MAAM,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpC,IAAI,CAAC,GAAG,CAAC,gCAAgC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC9E,CAAC;QACH,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,GAAG,CAAC,8BAA8B,cAAc,EAAE,CAAC,CAAC;YACzD,IAAI,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACnC,IAAI,CAAC,GAAG,CAAC,kBAAkB,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC/D,CAAC;YACD,IAAI,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACnC,IAAI,CAAC,GAAG,CAAC,sDAAsD,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACnG,CAAC;YACD,IAAI,MAAM,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpC,IAAI,CAAC,GAAG,CAAC,kBAAkB,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAChE,CAAC;QACH,CAAC;QAED,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;YACvB,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;QAC5D,CAAC;QAED,MAAM,iBAAiB,GAAG,MAAM,CAAC,iBAAiB,CAAC;QACnD,IAAI,iBAAiB,EAAE,MAAM,KAAK,OAAO,EAAE,CAAC;YAC1C,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC;YACtD,IAAI,CAAC,GAAG,CACN,GAAG,IAAI,KAAK,iBAAiB,CAAC,OAAO,oEAAoE,CAC1G,CAAC;YACF,IAAI,iBAAiB,CAAC,cAAc,EAAE,CAAC;gBACrC,IAAI,CAAC,GAAG,CACN,yGAAyG;oBACvG,iDAAiD,CACpD,CAAC;YACJ,CAAC;QACH,CAAC;QAED,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACtC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACrB,CAAC;QAED,IAAI,MAAM,CAAC,mBAAmB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1C,IAAI,CAAC,GAAG,CAAC,0CAA0C,MAAM,CAAC,mBAAmB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC3F,IAAI,CAAC,GAAG,CAAC,uBAAuB,MAAM,CAAC,mBAAmB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1E,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAEO,cAAc,CAAC,WAA8B,EAAE,MAAe;QACpE,MAAM,KAAK,GAAG;YACZ,KAAK,EAAE,4CAA4C;YACnD,MAAM,EAAE,iCAAiC;YACzC,GAAG,EAAE,wBAAwB;SAC9B,CAAC;QACF,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,KAAK,SAAS,CAAC;QACjD,IAAI,WAAW,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzC,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;YACpG,MAAM,SAAS,GAAG,WAAW,CAAC,SAAS,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,WAAW,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAChG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,IAAI,WAAW,CAAC,IAAI,WAAW,WAAW,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,SAAS,EAAE,CAAC,CAAC;QACrG,CAAC;aAAM,IAAI,WAAW,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;YAC9C,IAAI,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,IAAI,iCAAiC,CAAC,CAAC;QACjE,CAAC;aAAM,IAAI,WAAW,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC5C,IAAI,CAAC,GAAG,CACN,WAAW,WAAW,CAAC,IAAI,QAAQ,WAAW,CAAC,IAAI,+BAA+B;gBAChF,oGAAoG,CACvG,CAAC;QACJ,CAAC;QACD,KAAK,MAAM,OAAO,IAAI,WAAW,CAAC,QAAQ,EAAE,CAAC;YAC3C,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACrB,CAAC;IACH,CAAC"}
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"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"}

package/lib/commands/snapshot/console/import.d.ts

@@ -0,0 +1,26 @@
+import { Command } from '@oclif/core';
+import { type DomSnapshotMeta } from '@simplysf/simply-utam-core';
+import { type Clipboard } from '../../../clipboard.js';
+export type ImportResult = {
+    file: string;
+    meta: DomSnapshotMeta;
+};
+/**
+ * Save a DOM snapshot captured outside a test run, such as by the console snippet.
+ */
+export default class SnapshotConsoleImport extends Command {
+    static summary: string;
+    static description: string;
+    static examples: string[];
+    static enableJsonFlag: boolean;
+    static flags: {
+        'project-dir': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        label: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    /** The clipboard read without --file; tests replace it. */
+    clipboard: Clipboard;
+    /** Standard input, for `--file -`; tests replace it. */
+    stdin: NodeJS.ReadableStream;
+    run(): Promise<ImportResult>;
+}

package/lib/commands/snapshot/console/import.js

@@ -0,0 +1,96 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { Command, Flags } from '@oclif/core';
+import { DomSnapshotError, MANUAL_RUN_ID, importDomSnapshot, writeDomSnapshot, } from '@simplysf/simply-utam-core';
+import { ClipboardUnavailableError, systemClipboard } from '../../../clipboard.js';
+import { BAD_INPUT, headerFor, projectDirFlag } from '../../../snapshot-flags.js';
+async function readAll(stream) {
+    const chunks = [];
+    for await (const chunk of stream)
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+    return Buffer.concat(chunks).toString('utf8');
+}
+/**
+ * Save a DOM snapshot captured outside a test run, such as by the console snippet.
+ */
+export default class SnapshotConsoleImport extends Command {
+    static summary = 'Save the DOM snapshot the console snippet copied, or any snapshot file.';
+    static description = 'Reads the clipboard by default, or --file (- for standard input). Checks the snapshot, saves it to .utam/snapshots/manual/ as manual--<label or number>.json and to latest.json, and prints the header every snapshot command prints. The rest of the snapshot is kept as captured.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --label "account list"',
+        '<%= config.bin %> <%= command.id %> --file ~/Downloads/dom-snapshot-20261019T120000.json',
+        'pbpaste | <%= config.bin %> <%= command.id %> --file -',
+    ];
+    static enableJsonFlag = true;
+    static flags = {
+        file: Flags.string({
+            summary: 'Snapshot file to read instead of the clipboard, relative to the current folder; - for standard input.',
+        }),
+        label: Flags.string({ summary: 'Label for the snapshot, used in its file name and header.' }),
+        ...projectDirFlag,
+    };
+    /** The clipboard read without --file; tests replace it. */
+    clipboard = systemClipboard();
+    /** Standard input, for `--file -`; tests replace it. */
+    stdin = process.stdin;
+    async run() {
+        const { flags } = await this.parse(SnapshotConsoleImport);
+        const source = flags.file === '-' ? 'standard input' : (flags.file ?? 'clipboard');
+        let text;
+        try {
+            text =
+                flags.file === '-'
+                    ? await readAll(this.stdin)
+                    : flags.file
+                        ? await fs.readFile(path.resolve(flags.file), 'utf8')
+                        : await this.clipboard.read();
+        }
+        catch (error) {
+            if (error instanceof ClipboardUnavailableError)
+                this.error(`Can't read the clipboard: ${error.message}. Use --file <path>, or --file - for standard input.`, {
+                    exit: BAD_INPUT,
+                });
+            if (error.code === 'ENOENT')
+                this.error(`No such file: ${source}`, { exit: BAD_INPUT });
+            throw error;
+        }
+        if (!text.trim()) {
+            this.error(`The ${source} is empty. Run the snippet (\`npx simply-utam snapshot console snippet --copy\`) in the page's DevTools console first.`, { exit: BAD_INPUT });
+        }
+        let snapshot;
+        try {
+            snapshot = importDomSnapshot(text, { label: flags.label });
+        }
+        catch (error) {
+            if (error instanceof DomSnapshotError)
+                this.error(`The ${source} doesn't hold a DOM snapshot: ${error.message}`, { exit: BAD_INPUT });
+            throw error;
+        }
+        if (snapshot.meta.mask === 'full')
+            this.warn('This snapshot was captured with mask "full": it keeps record data.');
+        const projectDir = flags['project-dir'];
+        const file = await writeDomSnapshot(snapshot, { projectDir, runId: MANUAL_RUN_ID });
+        // From the snapshot in memory: the header doesn't show the package versions the file gains.
+        const header = headerFor(projectDir, path.join(projectDir, file), snapshot);
+        this.log(`DOM snapshot saved to ${file}`);
+        for (const line of header)
+            this.log(line);
+        return { file, meta: snapshot.meta };
+    }
+}
+//# sourceMappingURL=import.js.map

package/lib/commands/snapshot/console/import.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"import.js","sourceRoot":"","sources":["../../../../src/commands/snapshot/console/import.ts"],"names":[],"mappings":"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"}

package/lib/commands/snapshot/console/snippet.d.ts

@@ -0,0 +1,25 @@
+import { Command } from '@oclif/core';
+import { type Clipboard } from '../../../clipboard.js';
+export type SnippetResult = {
+    snippet: string;
+    copied: boolean;
+};
+/**
+ * Print the console snippet that captures a DOM snapshot, or copy it to the clipboard.
+ */
+export default class SnapshotConsoleSnippet extends Command {
+    static summary: string;
+    static description: string;
+    static examples: string[];
+    static enableJsonFlag: boolean;
+    static flags: {
+        copy: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        mask: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        focus: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'max-nodes': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'max-hidden-nodes': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    /** The clipboard `--copy` writes to; tests replace it. */
+    clipboard: Clipboard;
+    run(): Promise<SnippetResult>;
+}

package/lib/commands/snapshot/console/snippet.js

@@ -0,0 +1,72 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Command, Flags } from '@oclif/core';
+import { domSnapshotSnippet } from '@simplysf/simply-utam-core';
+import { ClipboardUnavailableError, systemClipboard } from '../../../clipboard.js';
+import { BAD_INPUT } from '../../../snapshot-flags.js';
+/**
+ * Print the console snippet that captures a DOM snapshot, or copy it to the clipboard.
+ */
+export default class SnapshotConsoleSnippet extends Command {
+    static summary = "The snippet to paste into a browser's DevTools console to capture a DOM snapshot.";
+    static description = "Paste it into the console of the page to capture, with the console's context set to top. It runs the same walker a test run does, masks the page there, copies the snapshot JSON to the clipboard and prints a summary; save it with `snapshot console import`. Where the console's copy() isn't available, it downloads the JSON instead, for `import --file`. The mask is fixed in the snippet.";
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --copy',
+        '<%= config.bin %> <%= command.id %> --mask structure --copy',
+        '<%= config.bin %> <%= command.id %> > snippet.js',
+    ];
+    static enableJsonFlag = true;
+    static flags = {
+        copy: Flags.boolean({ summary: 'Copy the snippet to the clipboard instead of printing it.', default: false }),
+        mask: Flags.string({
+            summary: 'Mask mode, from least kept to most. Defaults to UTAM_SNAPSHOT_MASK, then labels.',
+            options: ['structure', 'labels', 'aria', 'full'],
+        }),
+        focus: Flags.string({
+            summary: 'Where the walk starts: auto (the active Lightning page or console tab), none, or a CSS selector.',
+            default: 'auto',
+        }),
+        'max-nodes': Flags.integer({ summary: 'Most visible nodes to capture.', min: 1 }),
+        'max-hidden-nodes': Flags.integer({ summary: 'Most hidden nodes to capture.', min: 1 }),
+    };
+    /** The clipboard `--copy` writes to; tests replace it. */
+    clipboard = systemClipboard();
+    async run() {
+        const { flags } = await this.parse(SnapshotConsoleSnippet);
+        const snippet = domSnapshotSnippet({
+            mask: flags.mask,
+            focus: flags.focus,
+            maxNodes: flags['max-nodes'],
+            maxHiddenNodes: flags['max-hidden-nodes'],
+            log: (message) => this.warn(message),
+        });
+        if (!flags.copy) {
+            this.log(snippet);
+            return { snippet, copied: false };
+        }
+        try {
+            await this.clipboard.write(snippet);
+        }
+        catch (error) {
+            if (!(error instanceof ClipboardUnavailableError))
+                throw error;
+            this.error(`Can't copy the snippet: ${error.message}. Run without --copy to print it.`, { exit: BAD_INPUT });
+        }
+        this.log('Snippet copied. Paste it into the DevTools console of the page to capture (context: top), then run `npx simply-utam snapshot console import`.');
+        return { snippet, copied: true };
+    }
+}
+//# sourceMappingURL=snippet.js.map