@crouton-kit/capture 1.3.21 → 1.4.0

package/src/output/selector.ts

@@ -30,6 +30,8 @@ export interface ElementRecord {
   readonly axName?: string;
   /** Text content associated with the element, when known. */
   readonly text?: string;
+  /** The element's own captured HTML attributes, keyed by attribute name. */
+  readonly attributes?: Readonly<Record<string, string>>;
   readonly [key: string]: unknown;
 }
 
@@ -37,9 +39,240 @@ export interface ElementRecord {
 // Direct lookups
 // ============================================================================
 
-/** Elements whose stored `selector` exactly equals `selector`. */
+interface AttributeMatcher {
+  readonly name: string;
+  readonly value?: string;
+}
+
+interface CompoundMatcher {
+  readonly tag?: string;
+  readonly id?: string;
+  readonly classes: readonly string[];
+  readonly attributes: readonly AttributeMatcher[];
+  readonly nthOfType?: number;
+}
+
+type Combinator = 'child' | 'descendant';
+
+interface CssMatcher {
+  readonly compounds: readonly CompoundMatcher[];
+  /** The relation between compound i and compound i + 1. */
+  readonly combinators: readonly Combinator[];
+}
+
+function isNameStart(char: string | undefined): boolean {
+  return char !== undefined && /[A-Za-z_*]/.test(char);
+}
+
+function isNameChar(char: string | undefined): boolean {
+  return char !== undefined && /[A-Za-z0-9_-]/.test(char);
+}
+
+function readName(value: string, start: number): { value: string; end: number } | undefined {
+  if (!isNameStart(value[start])) return undefined;
+  let end = start + 1;
+  while (isNameChar(value[end])) end += 1;
+  return { value: value.slice(start, end), end };
+}
+
+function unquoteCssValue(value: string): string | undefined {
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+    return trimmed.slice(1, -1).replace(/\\(.)/g, '$1');
+  }
+  return /\s/.test(trimmed) ? undefined : trimmed;
+}
+
+function parseAttribute(value: string): AttributeMatcher | undefined {
+  const equals = value.indexOf('=');
+  const name = (equals === -1 ? value : value.slice(0, equals)).trim();
+  if (!/^[A-Za-z_][A-Za-z0-9_:-]*$/.test(name)) return undefined;
+  if (equals === -1) return { name: name.toLowerCase() };
+  const attributeValue = unquoteCssValue(value.slice(equals + 1));
+  return attributeValue === undefined ? undefined : { name: name.toLowerCase(), value: attributeValue };
+}
+
+function parseCompound(value: string): CompoundMatcher | undefined {
+  let index = 0;
+  let tag: string | undefined;
+  const first = readName(value, index);
+  if (first) {
+    tag = first.value.toLowerCase();
+    index = first.end;
+  }
+  const classes: string[] = [];
+  const attributes: AttributeMatcher[] = [];
+  let id: string | undefined;
+  let nthOfType: number | undefined;
+  while (index < value.length) {
+    const marker = value[index]!;
+    if (marker === '.' || marker === '#') {
+      const name = readName(value, index + 1);
+      if (!name) return undefined;
+      if (marker === '.') classes.push(name.value);
+      else if (id === undefined) id = name.value;
+      else return undefined;
+      index = name.end;
+      continue;
+    }
+    if (marker === '[') {
+      let end = index + 1;
+      let quote: string | undefined;
+      while (end < value.length) {
+        const char = value[end]!;
+        if (quote) {
+          if (char === '\\') end += 2;
+          else {
+            if (char === quote) quote = undefined;
+            end += 1;
+          }
+        } else if (char === '"' || char === "'") {
+          quote = char;
+          end += 1;
+        } else if (char === ']') break;
+        else end += 1;
+      }
+      if (quote || value[end] !== ']') return undefined;
+      const attribute = parseAttribute(value.slice(index + 1, end));
+      if (!attribute) return undefined;
+      attributes.push(attribute);
+      index = end + 1;
+      continue;
+    }
+    if (value.startsWith(':nth-of-type(', index)) {
+      const end = value.indexOf(')', index);
+      const rawIndex = value.slice(index + ':nth-of-type('.length, end);
+      if (end === -1 || !/^\d+$/.test(rawIndex) || nthOfType !== undefined) return undefined;
+      nthOfType = Number(rawIndex);
+      index = end + 1;
+      continue;
+    }
+    return undefined;
+  }
+  return tag || id || classes.length || attributes.length || nthOfType !== undefined ? { tag, id, classes, attributes, nthOfType } : undefined;
+}
+
+function parseCssMatcher(rawInput: string): CssMatcher | undefined {
+  const input = rawInput.trim();
+  const compounds: CompoundMatcher[] = [];
+  const combinators: Combinator[] = [];
+  let index = 0;
+  let pendingCombinator: Combinator | undefined;
+  while (index < input.length) {
+    let sawWhitespace = false;
+    while (/\s/.test(input[index] ?? '')) {
+      sawWhitespace = true;
+      index += 1;
+    }
+    if (index >= input.length) return undefined;
+    if (input[index] === '>') {
+      if (!compounds.length || pendingCombinator) return undefined;
+      pendingCombinator = 'child';
+      index += 1;
+      continue;
+    }
+    if (compounds.length && !pendingCombinator) pendingCombinator = sawWhitespace ? 'descendant' : undefined;
+    if (compounds.length && !pendingCombinator) return undefined;
+    const start = index;
+    let bracketDepth = 0;
+    let quote: string | undefined;
+    while (index < input.length) {
+      const char = input[index]!;
+      if (quote) {
+        if (char === '\\') index += 2;
+        else {
+          if (char === quote) quote = undefined;
+          index += 1;
+        }
+      } else if (char === '"' || char === "'") {
+        quote = char;
+        index += 1;
+      } else if (char === '[') {
+        bracketDepth += 1;
+        index += 1;
+      } else if (char === ']') {
+        bracketDepth -= 1;
+        if (bracketDepth < 0) return undefined;
+        index += 1;
+      } else if (bracketDepth === 0 && (char === '>' || /\s/.test(char))) break;
+      else index += 1;
+    }
+    if (quote || bracketDepth !== 0) return undefined;
+    const compound = parseCompound(input.slice(start, index));
+    if (!compound) return undefined;
+    if (compounds.length) combinators.push(pendingCombinator!);
+    compounds.push(compound);
+    pendingCombinator = undefined;
+  }
+  return compounds.length && !pendingCombinator ? { compounds, combinators } : undefined;
+}
+
+function elementAttributes(element: ElementRecord): Readonly<Record<string, string>> {
+  return element.attributes ?? {};
+}
+
+function terminalGeneratedCompound(element: ElementRecord): CompoundMatcher | undefined {
+  const selector = element.selector;
+  if (!selector) return undefined;
+  const parts = parseCssMatcher(selector)?.compounds;
+  return parts?.at(-1);
+}
+
+function matchesCompound(element: ElementRecord, compound: CompoundMatcher): boolean {
+  const tag = element.tag;
+  if (compound.tag && compound.tag !== '*' && (typeof tag !== 'string' || tag.toLowerCase() !== compound.tag)) return false;
+  const attributes = elementAttributes(element);
+  const generated = terminalGeneratedCompound(element);
+  const actualId = attributes.id ?? generated?.id;
+  if (compound.id && actualId !== compound.id) return false;
+  const classNames = new Set((attributes.class ?? '').split(/\s+/).filter(Boolean));
+  for (const className of generated?.classes ?? []) classNames.add(className);
+  if (compound.classes.some((className) => !classNames.has(className))) return false;
+  for (const attribute of compound.attributes) {
+    const actual = Object.entries(attributes).find(([name]) => name.toLowerCase() === attribute.name)?.[1];
+    if (actual === undefined || (attribute.value !== undefined && actual !== attribute.value)) return false;
+  }
+  if (compound.nthOfType !== undefined && generated?.nthOfType !== compound.nthOfType) return false;
+  return true;
+}
+
+function pathSegments(element: ElementRecord): readonly string[] | undefined {
+  const domPath = element.domPath;
+  return typeof domPath === 'string' && domPath ? domPath.split('/') : undefined;
+}
+
+function treeScope(element: ElementRecord): string | undefined {
+  const frame = element.frame;
+  if (typeof frame !== 'object' || frame === null || typeof (frame as Record<string, unknown>).frameId !== 'string') return undefined;
+  const shadow = element.shadow;
+  if (typeof shadow !== 'object' || shadow === null || (shadow as Record<string, unknown>).inShadowDom !== true) return `${(frame as Record<string, unknown>).frameId}:light`;
+  const values = shadow as Record<string, unknown>;
+  return `${(frame as Record<string, unknown>).frameId}:shadow:${String(values.chainDepth)}:${String(values.hostSelector)}`;
+}
+
+function isAncestorOf(ancestor: ElementRecord, descendant: ElementRecord, direct: boolean): boolean {
+  const ancestorPath = pathSegments(ancestor);
+  const descendantPath = pathSegments(descendant);
+  if (!ancestorPath || !descendantPath || ancestorPath.length >= descendantPath.length || treeScope(ancestor) !== treeScope(descendant)) return false;
+  if (direct && ancestorPath.length !== descendantPath.length - 1) return false;
+  return ancestorPath.every((segment, index) => descendantPath[index] === segment);
+}
+
+function matchesCssMatcher(elements: readonly ElementRecord[], target: ElementRecord, matcher: CssMatcher, index = matcher.compounds.length - 1): boolean {
+  if (!matchesCompound(target, matcher.compounds[index]!)) return false;
+  if (index === 0) return true;
+  const direct = matcher.combinators[index - 1] === 'child';
+  return elements.some((candidate) => isAncestorOf(candidate, target, direct) && matchesCssMatcher(elements, candidate, matcher, index - 1));
+}
+
+/** Elements matching the supported CSS subset against their recorded DOM facts.
+ * A verbatim collector-generated selector remains an exact lookup. */
 export function findBySelector(elements: readonly ElementRecord[], selector: string): ElementRecord[] {
-  return elements.filter((e) => e.selector === selector);
+  const exact = elements.filter((element) => element.selector === selector);
+  if (exact.length) return exact;
+  const matcher = parseCssMatcher(selector);
+  return matcher ? elements.filter((element) => matchesCssMatcher(elements, element, matcher)) : [];
 }
 
 /** The element with this `backendNodeId`, if any. */
@@ -101,9 +334,9 @@ export interface ParsedSelectorInput {
  *  - `axid:<id>`    — accessibility node id
  *  - `ax:<name>`    — accessibility name (substring)
  *  - `text:<needle>`— text content (substring)
- *  - anything else  — a CSS-ish selector, matched exactly against the
- *    collector's stored `selector` string (the form every design sample
- *    uses, e.g. `--selector ".toast-container"`)
+ *  - anything else  — a supported CSS selector: tag, `#id`, `.class`,
+ *    `[attr]`, `[attr="value"]`, and descendant/child compound sequences,
+ *    or a verbatim collector-generated selector path.
  */
 export function parseSelectorInput(input: string): ParsedSelectorInput {
   const prefixes: Array<[string, SelectorInputKind]> = [

package/src/session/commands.ts

@@ -330,40 +330,39 @@ export async function waitForPageLoad(
 
 /** Root-help representation of this branch, assembled by `src/capture.ts`. */
 export const COMMAND_BLOCK = `<command name="session">
-the artifact container — a session records HAR and bundles every artifact; it may open a tab or adopt one later; while active, every command auto-targets its tab
-use when starting scoped work against a page: start first, then every other capture command needs no --target/--port threading
+the artifact container — a session records HAR and bundles every artifact; it may open or adopt a tab; once it has one, every command auto-targets it
+use when starting scoped work against a page: start with --url or --target, then every other capture command needs no --target/--port threading
   start · stop · list · view · har · log — \`capture session -h\`
 </command>`;
 
-const START_USAGE = `capture session start [--url <url>] [--hold] — open or prepare a tab, record HAR, and set the active capture context.
+const START_USAGE = `capture session start [--url <url> | --target <tab-id>] [--hold] [--port <n>] — open or adopt a tab, record HAR, and set the active capture context.
 
 input:
-  --url <url>    Absolute URL to open in a fresh tab through CDP's
-                 Target.createTarget. Some endpoints, including Electron,
-                 expose existing tabs but reject Target.createTarget; on those
-                 endpoints --url cannot be used.
-  --hold         Hold one CDP browser connection open for the session's
-                 lifetime, so browser-level state (permission grants,
-                 ServiceWorker enablement) survives across separate commands.
-                 With no --url, start a held session and adopt an existing tab
-                 with this supported workflow:
-                   capture session start --hold --port <port>
-                   capture tab list --port <port>
-                   capture page navigate <url> --target <target-id> --port <port>
-                 The navigate command adopts that target for the session; later
-                 page commands then auto-target it.
-  --port <n>     CDP port to attach to; default is auto-detected across localhost.
+  --url <url>       Absolute URL to open in a fresh tab through CDP's
+                    Target.createTarget. Some endpoints, including Electron,
+                    expose existing tabs but reject Target.createTarget; on
+                    those endpoints --url cannot be used. Conflicts with
+                    --target.
+  --target <tab-id>  Existing page tab to adopt. Resolves a full target id or
+                    an unambiguous prefix of at least four characters at the
+                    selected CDP endpoint; start fails if it does not resolve.
+                    CDP_TARGET does not select a tab for session start. Conflicts
+                    with --url.
+  --hold             Hold one CDP browser connection open for the session's
+                    lifetime, so browser-level state (permission grants,
+                    ServiceWorker enablement) survives across separate commands.
+  --port <n>         CDP port to attach to; default is auto-detected across localhost.
 
 Output:
-  One <session id=… path=… [url=…]> block: the session id, bundle dir, opened
-  tab when --url succeeds, HAR recording id, and held-bridge pid when
+  One <session id=… path=… [url=…] [target=… port=…]> block: the session id,
+  bundle dir, opened or adopted tab, HAR recording id, and held-bridge pid when
   applicable. --json mirrors the same fields.
 
 effects:
   Creates a private session dir with shots/, starts a HAR recording, opens a
-  fresh tab only when --url is supplied, optionally holds a CDP bridge, and
-  registers the session as the active capture context so subsequent commands
-  auto-target it.`;
+  fresh tab only when --url is supplied or adopts the resolved --target tab,
+  optionally holds a CDP bridge, and registers the session as the active capture
+  context so subsequent commands auto-target its tab.`;
 
 const STOP_USAGE = `capture session stop <session-id> — finalize a session and write its bundle manifest.
 
@@ -475,13 +474,13 @@ effects:
   the identity-bearing tailer record is registered in the session metadata.`;
 
 function printSessionHelp(): void {
-  console.log(`capture session — the artifact container: records HAR and bundles artifacts; it may open a tab or adopt one later.
+  console.log(`capture session — the artifact container: records HAR and bundles artifacts; it may open or adopt a tab.
 
-An active session auto-targets its tab and auto-appends recorded traffic — no
+An active session with a tab auto-targets it and auto-appends recorded traffic — no
 --target/--har threading. \`stop\` finalizes the session and writes its bundle
 manifest; \`view\` reads that manifest back.
 
-  <subcommand name="start" args="[--url <url>] [--hold]" whenToUse="open or prepare a tab, start HAR, and set the active capture context"/>
+  <subcommand name="start" args="[--url <url> | --target <tab-id>] [--hold] [--port <n>]" whenToUse="open or adopt a tab, start HAR, and set the active capture context"/>
   <subcommand name="stop" args="<session-id>" whenToUse="finalize the session and write its bundle manifest"/>
   <subcommand name="list" args="" whenToUse="show active and stopped sessions"/>
   <subcommand name="view" args="<session-id> [--filter shots|har|logs|measure|motion|other]" whenToUse="read back a stopped session's bundle manifest"/>
@@ -506,6 +505,7 @@ export interface SessionStartWorld {
   deleteHar(harId: string): Promise<void>;
   detectCdpPort(): Promise<number>;
   openTab(port: number, url: string): Promise<CDPTarget>;
+  findTabById(port: number, targetId: string): Promise<CDPTarget | null>;
   closeTarget(port: number, targetId: string): Promise<void>;
   /** Attach to the freshly-opened tab and wait for load; returns page-load-timed-out. */
   awaitTabReady(target: CDPTarget, url: string): Promise<boolean>;
@@ -527,6 +527,10 @@ const productionStartWorld: SessionStartWorld = {
     const { openTab } = await import('../cdp.js');
     return openTab(port, url);
   },
+  async findTabById(port, targetId) {
+    const { findTabById } = await import('../cdp/targets.js');
+    return findTabById(port, targetId);
+  },
   async closeTarget(port, targetId) {
     const { closeTarget } = await import('../cdp/targets.js');
     return closeTarget(port, targetId);
@@ -600,7 +604,7 @@ async function start(parsed: ParsedArgs): Promise<void> {
     return;
   }
 
-  if (rejectSurplusPositionals(parsed, 'start', 0, 'capture session start [--url <url>] [--hold]')) return;
+  if (rejectSurplusPositionals(parsed, 'start', 0, 'capture session start [--url <url> | --target <tab-id>] [--hold] [--port <n>]')) return;
 
   return withSessionScopeLifecycle(async () => {
     const active = getActiveSession();
@@ -616,6 +620,7 @@ async function start(parsed: ParsedArgs): Promise<void> {
     }
 
     const url = parsed.url ?? null;
+    const requestedTarget = parsed.target ?? null;
     const hold = parsed.hold === true;
     const id = generateId();
     const dir = sessionDir(id);
@@ -639,10 +644,20 @@ async function start(parsed: ParsedArgs): Promise<void> {
       const acquiredHarId = harId;
       acquired.push({ label: 'HAR recording', release: () => startWorld.deleteHar(acquiredHarId) });
 
-      if (url || hold) {
+      if (url || requestedTarget || hold) {
         cdpPort = parsed.port ?? await startWorld.detectCdpPort();
       }
 
+      if (requestedTarget) {
+        target = await startWorld.findTabById(cdpPort!, requestedTarget);
+        if (!target) {
+          throw worldFailure(`No tab found for target "${requestedTarget}" on port ${cdpPort}. Run \`capture tab list --port ${cdpPort}\` to see available tabs.`);
+        }
+        if (target.type !== 'page') {
+          throw worldFailure(`Target "${requestedTarget}" on port ${cdpPort} is ${target.type}, not a page tab. Run \`capture tab list --port ${cdpPort}\` to see available tabs.`);
+        }
+      }
+
       if (url) {
         try {
           target = await startWorld.openTab(cdpPort!, url);
@@ -650,7 +665,7 @@ async function start(parsed: ParsedArgs): Promise<void> {
           const message = error instanceof Error ? error.message : String(error);
           if (message.toLowerCase().includes('not supported')) {
             throw worldFailure(
-              `Target.createTarget is unsupported on port ${cdpPort}. Use existing tab: \`capture page navigate <url> --target <target-id> --port ${cdpPort}\` after \`capture session start --hold --port ${cdpPort}\` and \`capture tab list\`.`,
+              `Target.createTarget is unsupported on port ${cdpPort}. Use an existing tab: \`capture tab list --port ${cdpPort}\`, then \`capture session start --target <target-id> --port ${cdpPort}\`.`,
               error,
             );
           }
@@ -680,7 +695,7 @@ async function start(parsed: ParsedArgs): Promise<void> {
         startedAt: new Date().toISOString(),
         stoppedAt: null,
         stopping: false,
-        url,
+        url: target?.url ?? url,
         targetId: target?.id ?? null,
         port: cdpPort,
         stepCount: 0,
@@ -699,14 +714,14 @@ async function start(parsed: ParsedArgs): Promise<void> {
     }
 
     const rows: FactLine[] = [fact`bundle dir: ${dir}`];
-    if (target) rows.push(fact`tab ${target.id} opened at ${url ?? ''}`);
+    if (target) rows.push(url ? fact`tab ${target.id} opened at ${url}` : fact`tab ${target.id} adopted at ${target.url}`);
     if (pageLoadTimedOut) rows.push(fact`page load timed out after 10000ms; the session stays attached to target ${target?.id ?? ''}`);
     if (harId) rows.push(fact`HAR recording ${harId} — traffic auto-appends while the session is active`);
     if (hold) rows.push(fact`held CDP bridge: pid ${bridgePid ?? 0}`);
 
     emitResult({
       tag: 'session',
-      attrs: { id, path: dir, ...(url ? { url } : {}) },
+      attrs: { id, path: dir, ...(target?.url ? { url: target.url } : {}), ...(target ? { target: target.id } : {}), ...(cdpPort !== null ? { port: cdpPort } : {}) },
       summary: fact`Session ${id} started; it is now the active capture context.`,
       sections: [lineList(rows)],
       followUp: fact`capture session stop ${id}`,

package/src/command-help.ts

@@ -1,29 +0,0 @@
-/** Pure specification-help assembly from Capture's descriptor tree. */
-import { type RegistryNode } from './registry.js';
-
-const usage = (node: RegistryNode): string => `capture${node.path ? ` ${node.path}` : ''}`;
-const parameter = (name: string, grammar: string, required: boolean, variadic = false): string => `  ${required ? '<' : '['}${name}${required ? '>' : ']'}  ${grammar}${variadic ? ' (variadic)' : ''}`;
-
-/** Renders only descriptor-owned content; help never parses inputs or performs effects. */
-export function assembleHelp(node: RegistryNode): string {
-  const { help } = node;
-  const lines = [usage(node), '', help.description, '', `When to use: ${help.whenToUse}`, `Model: ${help.model ?? help.rubric}`];
-  if (help.globals) lines.push('', 'Globals:', help.globals);
-  if (help.ioContract) lines.push('', `I/O contract: ${help.ioContract}`);
-  if (node.kind === 'branch') {
-    const children = node.children.filter((child) => child.visibility === 'public');
-    if (children.length) {
-      lines.push('', 'Commands:');
-      for (const child of children) lines.push(`  ${child.path.split(' ').at(-1)}  ${child.help.description} When to use: ${child.help.whenToUse}`);
-    }
-  } else {
-    if (node.positionals.length || node.flags.length) {
-      lines.push('', 'Parameters:');
-      for (const positional of node.positionals) lines.push(parameter(positional.name, positional.grammar, positional.required, positional.variadic));
-      for (const flag of node.flags) lines.push(`  ${flag.name}${flag.grammar === 'boolean' ? '' : ` <${flag.grammar}>`}${flag.required ? ' required' : ''}${flag.repeatable ? ' repeatable' : ''}${flag.default === undefined ? '' : ` default=${flag.default}`}${flag.values ? ` values=${flag.values.join('|')}` : ''}${flag.units ? ` units=${flag.units}` : ''}`);
-    }
-    lines.push('', `Constraints: ${help.constraints}`, `Output: ${help.orderedOutput}`, `Artifact ownership: ${help.artifactOwnership}`, `Effects: browser=${node.effects.browser}, session=${node.effects.session}, artifact=${node.effects.artifact}, environment=${node.effects.environment}`, `Recovery: ${node.recovery}`);
-  }
-  lines.push('', `Next action: ${help.followUp}`);
-  return `${lines.join('\n')}\n`;
-}

package/src/command-resolution.ts

@@ -1,22 +0,0 @@
-/** Pure pre-dispatch control precedence for U15's future launcher wiring. */
-import { assembleHelp } from './command-help.js';
-import { hasHelpFlag, hasRootVersionFlag, walkCommand } from './command-walker.js';
-import { CAPTURE_REGISTRY, type RegistryBranch, type RegistryNode } from './registry.js';
-
-export type CommandResolution =
-  | { readonly kind: 'version' }
-  | { readonly kind: 'help'; readonly node: RegistryNode; readonly text: string }
-  | { readonly kind: 'dispatch'; readonly node: RegistryNode; readonly argv: readonly string[] }
-  | { readonly kind: 'unknown-path'; readonly received: string; readonly expected: readonly string[]; readonly path: string };
-
-/**
- * Applies only control precedence. It deliberately does not parse leaf argv,
- * validate `--json`, invoke a handler, or allocate any effectful dependency.
- */
-export function resolveCommand(argv: readonly string[], root: RegistryBranch = CAPTURE_REGISTRY): CommandResolution {
-  if (hasRootVersionFlag(argv)) return { kind: 'version' };
-  const walked = walkCommand(argv, root);
-  if (walked.kind === 'unknown-path') return { kind: 'unknown-path', received: walked.received, expected: walked.expected, path: walked.resolved.path };
-  if (hasHelpFlag(walked.remaining)) return { kind: 'help', node: walked.node, text: assembleHelp(walked.node) };
-  return { kind: 'dispatch', node: walked.node, argv: walked.remaining };
-}

package/src/command-walker.ts

@@ -1,35 +0,0 @@
-/** Pure exact command-path resolution for the descriptor registry. */
-import { CAPTURE_REGISTRY, type RegistryBranch, type RegistryNode } from './registry.js';
-
-export type WalkResult =
-  | { readonly kind: 'resolved'; readonly node: RegistryNode; readonly remaining: readonly string[] }
-  | { readonly kind: 'unknown-path'; readonly received: string; readonly resolved: RegistryBranch; readonly expected: readonly string[]; readonly remaining: readonly string[] };
-
-/**
- * Resolves only exact canonical path tokens. It stops before the first option,
- * resolves the deepest known leaf/branch, and leaves all leaf argv untouched.
- * Parsing, output compatibility, effects, and handler dispatch are intentionally
- * outside this pure walker.
- */
-export function walkCommand(argv: readonly string[], root: RegistryBranch = CAPTURE_REGISTRY): WalkResult {
-  let current: RegistryNode = root;
-  let index = 0;
-  while (current.kind === 'branch' && index < argv.length) {
-    const token = argv[index];
-    if (token.startsWith('-')) break;
-    const child: RegistryNode | undefined = current.children.find((candidate: RegistryNode) => candidate.path.split(' ').at(-1) === token);
-    if (!child) return { kind: 'unknown-path', received: token, resolved: current, expected: current.children.filter((candidate) => candidate.visibility === 'public').map((candidate) => candidate.path.split(' ').at(-1)!), remaining: argv.slice(index) };
-    current = child;
-    index += 1;
-  }
-  return { kind: 'resolved', node: current, remaining: argv.slice(index) };
-}
-
-export function hasHelpFlag(argv: readonly string[]): boolean {
-  return argv.includes('-h') || argv.includes('--help');
-}
-
-/** Root version is the sole accepted version spelling and wins before walking. */
-export function hasRootVersionFlag(argv: readonly string[]): boolean {
-  return argv[0] === '--version';
-}