@simplysf/simply-utam 0.1.7 → 0.3.0

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"snippet.js","sourceRoot":"","sources":["../../../../src/commands/snapshot/console/snippet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAqB,MAAM,4BAA4B,CAAC;AACnF,OAAO,EAAE,yBAAyB,EAAE,eAAe,EAAkB,MAAM,uBAAuB,CAAC;AACnG,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAIvD;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,sBAAuB,SAAQ,OAAO;IAClD,MAAM,CAAU,OAAO,GAAG,mFAAmF,CAAC;IAE9G,MAAM,CAAU,WAAW,GAChC,mYAAmY,CAAC;IAE/X,MAAM,CAAU,QAAQ,GAAG;QAChC,4CAA4C;QAC5C,6DAA6D;QAC7D,kDAAkD;KACnD,CAAC;IAEK,MAAM,CAAU,cAAc,GAAG,IAAI,CAAC;IAEtC,MAAM,CAAU,KAAK,GAAG;QAC7B,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,2DAA2D,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC7G,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC;YACjB,OAAO,EAAE,kFAAkF;YAC3F,OAAO,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;SACjD,CAAC;QACF,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC;YAClB,OAAO,EAAE,kGAAkG;YAC3G,OAAO,EAAE,MAAM;SAChB,CAAC;QACF,WAAW,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,gCAAgC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;QACjF,kBAAkB,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,+BAA+B,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;KACxF,CAAC;IAEF,0DAA0D;IACnD,SAAS,GAAc,eAAe,EAAE,CAAC;IAEzC,KAAK,CAAC,GAAG;QACd,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;QAC3D,MAAM,OAAO,GAAG,kBAAkB,CAAC;YACjC,IAAI,EAAE,KAAK,CAAC,IAAgC;YAC5C,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,QAAQ,EAAE,KAAK,CAAC,WAAW,CAAC;YAC5B,cAAc,EAAE,KAAK,CAAC,kBAAkB,CAAC;YACzC,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;SACrC,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YAChB,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAClB,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QACpC,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,CAAC,KAAK,YAAY,yBAAyB,CAAC;gBAAE,MAAM,KAAK,CAAC;YAC/D,IAAI,CAAC,KAAK,CAAC,2BAA2B,KAAK,CAAC,OAAO,mCAAmC,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;QAC/G,CAAC;QACD,IAAI,CAAC,GAAG,CACN,+IAA+I,CAChJ,CAAC;QACF,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACnC,CAAC"}

package/lib/commands/snapshot/find.d.ts

@@ -0,0 +1,25 @@
+import { Command } from '@oclif/core';
+import { type FindResult } from '@simplysf/simply-utam-core';
+/**
+ * Find nodes in a DOM snapshot by text, attribute or tag.
+ */
+export default class SnapshotFind extends Command {
+    static summary: string;
+    static description: string;
+    static examples: string[];
+    static enableJsonFlag: boolean;
+    static flags: {
+        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        '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>;
+        text: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        attr: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        class: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        css: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        within: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        shadow: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<FindResult>;
+}

package/lib/commands/snapshot/find.js

@@ -0,0 +1,82 @@
+/*
+ * 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 { DomSnapshotError, findNodes } from '@simplysf/simply-utam-core';
+import { BAD_INPUT, fileFlag, limitFlag, loadSnapshot, projectDirFlag } from '../../snapshot-flags.js';
+/**
+ * Find nodes in a DOM snapshot by text, attribute or tag.
+ */
+export default class SnapshotFind extends Command {
+    static summary = 'Find nodes in a DOM snapshot by text, attribute, class, tag or CSS selector.';
+    static description = "Text matching is case-insensitive and substring, over each node's own text, its shadow text and its attribute values (not class). Record values are masked, so search by labels. Visible matches are listed first, in document order; hidden matches are counted, or listed with --all. --attr name=value is a case-insensitive substring match; --class matches one whole class token. --css tests a selector as UTAM's findElement would: every match in document order, the first (the one UTAM takes) marked, hidden ones included. It searches the document, or with --within a node's light DOM (a page object's elements) or, adding --shadow, its shadow root (shadow elements).";
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --text "Account Name"',
+        '<%= config.bin %> <%= command.id %> --tag records-record-layout-item --all',
+        '<%= config.bin %> <%= command.id %> --attr title=Edit',
+        '<%= config.bin %> <%= command.id %> --css "lightning-button.slds-button_brand"',
+        '<%= config.bin %> <%= command.id %> --css "lightning-input" --within n5012 --shadow',
+    ];
+    static enableJsonFlag = true;
+    static flags = {
+        text: Flags.string({ summary: 'Text to match (case-insensitive substring).' }),
+        attr: Flags.string({ summary: 'Attribute to match: `name` (present) or `name=value` (substring).' }),
+        tag: Flags.string({ summary: 'Tag name to match exactly.' }),
+        class: Flags.string({ summary: 'A whole class token to match, as `.name` would (case-sensitive).' }),
+        css: Flags.string({
+            summary: 'A CSS selector to test as UTAM would: all matches in document order, the first marked.',
+            exclusive: ['text', 'attr', 'tag', 'class'],
+        }),
+        within: Flags.string({ summary: 'With --css: search under this node (its light DOM).', dependsOn: ['css'] }),
+        shadow: Flags.boolean({
+            summary: "With --css and --within: search the node's shadow root instead.",
+            // No default: oclif checks dependsOn against a default value too.
+            dependsOn: ['css', 'within'],
+        }),
+        all: Flags.boolean({ summary: 'List hidden matches in full rather than as a count.', default: false }),
+        ...fileFlag,
+        ...projectDirFlag,
+        ...limitFlag,
+    };
+    async run() {
+        const { flags } = await this.parse(SnapshotFind);
+        if ([flags.text, flags.attr, flags.tag, flags.class, flags.css].every((value) => value === undefined)) {
+            this.error('Give --text, --attr, --class, --tag or --css.', { exit: BAD_INPUT });
+        }
+        try {
+            const { snapshot, header } = await loadSnapshot(flags['project-dir'], flags.file);
+            const result = findNodes(snapshot, {
+                text: flags.text,
+                attr: flags.attr,
+                tag: flags.tag,
+                class: flags.class,
+                css: flags.css,
+                within: flags.within,
+                shadow: flags.shadow,
+                all: flags.all,
+                limit: flags.limit,
+            });
+            for (const line of [...header, ...result.lines])
+                this.log(line);
+            return result.json;
+        }
+        catch (error) {
+            if (error instanceof DomSnapshotError)
+                this.error(error.message, { exit: BAD_INPUT });
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=find.js.map

package/lib/commands/snapshot/find.js.map

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

package/lib/commands/snapshot/lookup.d.ts

@@ -0,0 +1,20 @@
+import { Command } from '@oclif/core';
+import { type LookupResult, type SearchResult } from '@simplysf/simply-utam-core';
+/**
+ * Look up the page objects for a tag, or search them by keyword. Doesn't need a snapshot.
+ */
+export default class SnapshotLookup extends Command {
+    static summary: string;
+    static description: string;
+    static examples: string[];
+    static enableJsonFlag: boolean;
+    static args: {
+        tag: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static flags: {
+        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        'project-dir': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        search: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<LookupResult | SearchResult>;
+}

package/lib/commands/snapshot/lookup.js

@@ -0,0 +1,57 @@
+/*
+ * 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 { Args, Command, Flags } from '@oclif/core';
+import { buildPageObjectIndex, lookupPageObject, searchPageObjects, } from '@simplysf/simply-utam-core';
+import { BAD_INPUT, limitFlag, projectDirFlag } from '../../snapshot-flags.js';
+/**
+ * Look up the page objects for a tag, or search them by keyword. Doesn't need a snapshot.
+ */
+export default class SnapshotLookup extends Command {
+    static summary = 'Show the page objects for a tag, with their import paths, methods and elements; or search them.';
+    static description = "Reads the project's own page objects (from utam.config.json) and the page-object packages that generator.config.json namespaces and .utam/namespace-map.json map to, such as salesforce-pageobjects. A tag maps to a page object through a root selector, an element typed as that page object, or the naming convention. Where a tag maps to an implementation of an interface, the interface is reported, since test code loads the interface. Also accepts a page object name (such as recordHomeFlexipage2) instead of a tag. With --search, lists the page objects whose name, import path, tags or description contain every word given.";
+    static examples = [
+        '<%= config.bin %> <%= command.id %> lightning-input',
+        '<%= config.bin %> <%= command.id %> one-record-home-flexipage2',
+        '<%= config.bin %> <%= command.id %> recordLayoutItem',
+        '<%= config.bin %> <%= command.id %> --search "related list"',
+    ];
+    static enableJsonFlag = true;
+    static args = {
+        tag: Args.string({ description: 'A custom element tag, or a page object name.' }),
+    };
+    static flags = {
+        search: Flags.string({ summary: 'Words to search for in page object names, import paths, tags and descriptions.' }),
+        ...projectDirFlag,
+        ...limitFlag,
+    };
+    async run() {
+        const { args, flags } = await this.parse(SnapshotLookup);
+        if ((args.tag === undefined) === (flags.search === undefined)) {
+            this.error('Give a tag or page object name, or --search <words>, but not both.', { exit: BAD_INPUT });
+        }
+        const index = buildPageObjectIndex({ projectDir: flags['project-dir'] });
+        for (const warning of index.warnings)
+            this.warn(warning);
+        const options = { limit: flags.limit };
+        const result = flags.search === undefined
+            ? lookupPageObject(index, args.tag, options)
+            : searchPageObjects(index, flags.search, options);
+        for (const line of result.lines)
+            this.log(line);
+        return result.json;
+    }
+}
+//# sourceMappingURL=lookup.js.map

package/lib/commands/snapshot/lookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup.js","sourceRoot":"","sources":["../../../src/commands/snapshot/lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,GAGlB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE/E;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,cAAe,SAAQ,OAAO;IAC1C,MAAM,CAAU,OAAO,GAC5B,iGAAiG,CAAC;IAE7F,MAAM,CAAU,WAAW,GAChC,gnBAAgnB,CAAC;IAE5mB,MAAM,CAAU,QAAQ,GAAG;QAChC,qDAAqD;QACrD,gEAAgE;QAChE,sDAAsD;QACtD,6DAA6D;KAC9D,CAAC;IAEK,MAAM,CAAU,cAAc,GAAG,IAAI,CAAC;IAEtC,MAAM,CAAU,IAAI,GAAG;QAC5B,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,8CAA8C,EAAE,CAAC;KAClF,CAAC;IAEK,MAAM,CAAU,KAAK,GAAG;QAC7B,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,gFAAgF,EAAE,CAAC;QACnH,GAAG,cAAc;QACjB,GAAG,SAAS;KACb,CAAC;IAEK,KAAK,CAAC,GAAG;QACd,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QACzD,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,EAAE,CAAC;YAC9D,IAAI,CAAC,KAAK,CAAC,oEAAoE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;QACxG,CAAC;QACD,MAAM,KAAK,GAAG,oBAAoB,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;QACzE,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,QAAQ;YAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzD,MAAM,OAAO,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;QACvC,MAAM,MAAM,GACV,KAAK,CAAC,MAAM,KAAK,SAAS;YACxB,CAAC,CAAC,gBAAgB,CAAC,KAAK,EAAE,IAAI,CAAC,GAAI,EAAE,OAAO,CAAC;YAC7C,CAAC,CAAC,iBAAiB,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACtD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChD,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC"}

package/lib/commands/snapshot/node.d.ts

@@ -0,0 +1,22 @@
+import { Command } from '@oclif/core';
+import { type AncestorsResult, type NodeDetails } from '@simplysf/simply-utam-core';
+/**
+ * Print one node in full.
+ */
+export default class SnapshotNode extends Command {
+    static summary: string;
+    static description: string;
+    static examples: string[];
+    static enableJsonFlag: boolean;
+    static args: {
+        id: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static flags: {
+        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        '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>;
+        node: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        ancestors: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<NodeDetails | AncestorsResult>;
+}

package/lib/commands/snapshot/node.js

@@ -0,0 +1,61 @@
+/*
+ * 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 { Args, Command, Flags } from '@oclif/core';
+import { DomSnapshotError, nodeAncestors, nodeDetails, } from '@simplysf/simply-utam-core';
+import { BAD_INPUT, fileFlag, limitFlag, loadSnapshot, projectDirFlag } from '../../snapshot-flags.js';
+/**
+ * Print one node in full.
+ */
+export default class SnapshotNode extends Command {
+    static summary = 'Show everything a snapshot recorded about one node.';
+    static description = 'Its handle and its address (child positions from the page root, s for a step into a shadow root; the same in another snapshot of the same page). Every recorded attribute, unclipped; its own text and shadow text; its size and position; whether it is hidden, and under which node; its parent; and each of its light DOM and shadow root children in one line. With --ancestors, its ancestors instead, nearest first, one line each, with a line wherever the chain leaves a shadow root: for picking a container to scope a selector with.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> n5012',
+        '<%= config.bin %> <%= command.id %> --node n5012',
+        '<%= config.bin %> <%= command.id %> n5012 --ancestors',
+    ];
+    static enableJsonFlag = true;
+    static args = {
+        id: Args.string({ description: 'The node handle, such as n5012 (from find, path or tree).' }),
+    };
+    static flags = {
+        node: Flags.string({ summary: 'The node handle, instead of the argument.' }),
+        ancestors: Flags.boolean({ summary: "List the node's ancestors, nearest first, instead.", default: false }),
+        ...fileFlag,
+        ...projectDirFlag,
+        ...limitFlag,
+    };
+    async run() {
+        const { args, flags } = await this.parse(SnapshotNode);
+        const id = args.id ?? flags.node;
+        if (!id)
+            this.error('Give a node handle: snapshot node <n…>.', { exit: BAD_INPUT });
+        try {
+            const { snapshot, header } = await loadSnapshot(flags['project-dir'], flags.file);
+            const options = { limit: flags.limit };
+            const result = flags.ancestors ? nodeAncestors(snapshot, id, options) : nodeDetails(snapshot, id, options);
+            for (const line of [...header, ...result.lines])
+                this.log(line);
+            return result.json;
+        }
+        catch (error) {
+            if (error instanceof DomSnapshotError)
+                this.error(error.message, { exit: BAD_INPUT });
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=node.js.map

package/lib/commands/snapshot/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../../../src/commands/snapshot/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,WAAW,GAGZ,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEvG;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,YAAa,SAAQ,OAAO;IACxC,MAAM,CAAU,OAAO,GAAG,qDAAqD,CAAC;IAEhF,MAAM,CAAU,WAAW,GAChC,khBAAkhB,CAAC;IAE9gB,MAAM,CAAU,QAAQ,GAAG;QAChC,2CAA2C;QAC3C,kDAAkD;QAClD,uDAAuD;KACxD,CAAC;IAEK,MAAM,CAAU,cAAc,GAAG,IAAI,CAAC;IAEtC,MAAM,CAAU,IAAI,GAAG;QAC5B,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,2DAA2D,EAAE,CAAC;KAC9F,CAAC;IAEK,MAAM,CAAU,KAAK,GAAG;QAC7B,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,2CAA2C,EAAE,CAAC;QAC5E,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,oDAAoD,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC3G,GAAG,QAAQ;QACX,GAAG,cAAc;QACjB,GAAG,SAAS;KACb,CAAC;IAEK,KAAK,CAAC,GAAG;QACd,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QACvD,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC;QACjC,IAAI,CAAC,EAAE;YAAE,IAAI,CAAC,KAAK,CAAC,yCAAyC,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;QACpF,IAAI,CAAC;YACH,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,YAAY,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAClF,MAAM,OAAO,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;YACvC,MAAM,MAAM,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,QAAQ,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,QAAQ,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;YAC3G,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC;gBAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAChE,OAAO,MAAM,CAAC,IAAI,CAAC;QACrB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,gBAAgB;gBAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;YACtF,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC"}

package/lib/commands/snapshot/path.d.ts

@@ -0,0 +1,21 @@
+import { Command } from '@oclif/core';
+import { type FindResult, type PathResult } from '@simplysf/simply-utam-core';
+/**
+ * Show the component path to a node, with what the page-object index knows about each element.
+ */
+export default class SnapshotPath extends Command {
+    static summary: string;
+    static description: string;
+    static examples: string[];
+    static enableJsonFlag: boolean;
+    static flags: {
+        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        '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>;
+        node: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        text: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<PathResult | {
+        candidates: FindResult;
+    }>;
+}

package/lib/commands/snapshot/path.js

@@ -0,0 +1,77 @@
+/*
+ * 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 { buildPageObjectIndex, componentPath, componentPathByText, DomSnapshotError, } from '@simplysf/simply-utam-core';
+import { BAD_INPUT, fileFlag, limitFlag, loadSnapshot, projectDirFlag } from '../../snapshot-flags.js';
+/**
+ * Show the component path to a node, with what the page-object index knows about each element.
+ */
+export default class SnapshotPath extends Command {
+    static summary = 'Show the custom elements from the document down to a node, with their page objects.';
+    static description = 'Marks each shadow crossing and each hidden ancestor, and annotates each custom element with its page object (import path, and root when utam.load can load it), a likely route through a page object above it ("reachable through"), or "no page object found". With --text, prints the path only when exactly one visible node matches; otherwise lists the candidates and exits with code 1.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --node n5012',
+        '<%= config.bin %> <%= command.id %> --text "Account Name"',
+    ];
+    static enableJsonFlag = true;
+    static flags = {
+        node: Flags.string({
+            summary: 'The target node handle, such as n5012 (from find or tree).',
+            exactlyOne: ['node', 'text'],
+        }),
+        text: Flags.string({
+            summary: 'Find the target by text; it must have exactly one visible match.',
+            exactlyOne: ['node', 'text'],
+        }),
+        ...fileFlag,
+        ...projectDirFlag,
+        ...limitFlag,
+    };
+    async run() {
+        const { flags } = await this.parse(SnapshotPath);
+        try {
+            // Built once, after the snapshot is read, so a missing snapshot doesn't index every package first.
+            let built;
+            const pageObjects = () => {
+                if (!built) {
+                    built = buildPageObjectIndex({ projectDir: flags['project-dir'] });
+                    for (const warning of built.warnings)
+                        this.warn(warning);
+                }
+                return built;
+            };
+            const { snapshot, header } = await loadSnapshot(flags['project-dir'], flags.file, pageObjects);
+            const options = { index: pageObjects(), limit: flags.limit };
+            if (flags.node !== undefined) {
+                const result = componentPath(snapshot, flags.node, options);
+                for (const line of [...header, ...result.lines])
+                    this.log(line);
+                return result.json;
+            }
+            const result = componentPathByText(snapshot, flags.text, options);
+            for (const line of [...header, ...result.lines])
+                this.log(line);
+            process.exitCode = result.exitCode;
+            return result.json;
+        }
+        catch (error) {
+            if (error instanceof DomSnapshotError)
+                this.error(error.message, { exit: BAD_INPUT });
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=path.js.map

package/lib/commands/snapshot/path.js.map

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

package/lib/commands/snapshot/tree.d.ts

@@ -0,0 +1,19 @@
+import { Command } from '@oclif/core';
+import { type DomNode } from '@simplysf/simply-utam-core';
+/**
+ * Print the pruned tree under a node.
+ */
+export default class SnapshotTree extends Command {
+    static summary: string;
+    static description: string;
+    static examples: string[];
+    static enableJsonFlag: boolean;
+    static flags: {
+        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        '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>;
+        node: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        depth: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<DomNode>;
+}

package/lib/commands/snapshot/tree.js

@@ -0,0 +1,50 @@
+/*
+ * 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 { DomSnapshotError, subtree } from '@simplysf/simply-utam-core';
+import { BAD_INPUT, fileFlag, limitFlag, loadSnapshot, projectDirFlag } from '../../snapshot-flags.js';
+/**
+ * Print the pruned tree under a node.
+ */
+export default class SnapshotTree extends Command {
+    static summary = 'Print the pruned tree under a node, to a depth.';
+    static description = 'Each line is one node: tag, #id and .classes as CSS, other attributes, its own text and its shadow text, then its node handle (n…). "#shadow(mode)" lines mark a shadow root; "(hidden)" marks the top of a hidden subtree.';
+    static examples = ['<%= config.bin %> <%= command.id %> --node n5012 --depth 3'];
+    static enableJsonFlag = true;
+    static flags = {
+        node: Flags.string({ summary: 'The node to start at. Defaults to the snapshot root.' }),
+        depth: Flags.integer({ summary: 'How many levels below the node to print.', default: 3 }),
+        ...fileFlag,
+        ...projectDirFlag,
+        ...limitFlag,
+    };
+    async run() {
+        const { flags } = await this.parse(SnapshotTree);
+        try {
+            const { snapshot, header } = await loadSnapshot(flags['project-dir'], flags.file);
+            const result = subtree(snapshot, flags.node, { depth: flags.depth, limit: flags.limit });
+            for (const line of [...header, ...result.lines])
+                this.log(line);
+            return result.json;
+        }
+        catch (error) {
+            if (error instanceof DomSnapshotError)
+                this.error(error.message, { exit: BAD_INPUT });
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=tree.js.map

package/lib/commands/snapshot/tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../../../src/commands/snapshot/tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAgB,MAAM,4BAA4B,CAAC;AACrF,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEvG;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,YAAa,SAAQ,OAAO;IACxC,MAAM,CAAU,OAAO,GAAG,iDAAiD,CAAC;IAE5E,MAAM,CAAU,WAAW,GAChC,6NAA6N,CAAC;IAEzN,MAAM,CAAU,QAAQ,GAAG,CAAC,4DAA4D,CAAC,CAAC;IAE1F,MAAM,CAAU,cAAc,GAAG,IAAI,CAAC;IAEtC,MAAM,CAAU,KAAK,GAAG;QAC7B,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,sDAAsD,EAAE,CAAC;QACvF,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,0CAA0C,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QACzF,GAAG,QAAQ;QACX,GAAG,cAAc;QACjB,GAAG,SAAS;KACb,CAAC;IAEK,KAAK,CAAC,GAAG;QACd,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QACjD,IAAI,CAAC;YACH,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,YAAY,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAClF,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;YACzF,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC;gBAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAChE,OAAO,MAAM,CAAC,IAAI,CAAC;QACrB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,gBAAgB;gBAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;YACtF,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC"}

package/lib/snapshot-flags.d.ts

@@ -0,0 +1,40 @@
+import { type DomSnapshot, type PageObjectIndex } from '@simplysf/simply-utam-core';
+/** Flags the `snapshot` commands share. */
+export declare const fileFlag: {
+    file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+};
+export declare const projectDirFlag: {
+    'project-dir': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+};
+export declare const limitFlag: {
+    limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+};
+/** Exit code 2: bad input, such as a missing snapshot, an unknown handle, or conflicting arguments. */
+export declare const BAD_INPUT = 2;
+/** A snapshot a query command was pointed at, and its header. */
+export type LoadedSnapshot = {
+    snapshot: DomSnapshot;
+    header: string[];
+};
+/** The page-object index, or a function that builds it when it's needed. */
+export type IndexSource = PageObjectIndex | (() => PageObjectIndex);
+/**
+ * The header for a snapshot read from, or saved to, `file`, naming the file relative to the current
+ * folder.
+ *
+ * @param projectDir The test project.
+ * @param file The snapshot's file, absolute or relative to the current folder.
+ * @param snapshot The snapshot.
+ * @param index The page-object index, when the command has one; otherwise it's built only for UTAM's
+ * not-found error.
+ */
+export declare function headerFor(projectDir: string, file: string, snapshot: DomSnapshot, index?: IndexSource): string[];
+/**
+ * Read the snapshot a query command was pointed at, and the header that names it.
+ *
+ * @param projectDir The test project.
+ * @param file The `--file` flag; the project's latest snapshot when omitted.
+ * @param index The page-object index, when the command has one; otherwise it's built only for UTAM's
+ * not-found error.
+ */
+export declare function loadSnapshot(projectDir: string, file?: string, index?: IndexSource): Promise<LoadedSnapshot>;