@zq-silk/yui 1.1.2 → 2.1.0

package/dist/cli/commandDiscovery.js

@@ -0,0 +1,69 @@
+import { ROOT_COMMAND, findCommandNode } from "./commandCatalog.js";
+import { hasManagedIdentity } from "../runtime/managedIdentity.js";
+/** Offline presentation hints only. Execution still authenticates the original
+ * caller, including stale/incomplete identities, at its existing boundary. */
+export function discoveryAudience(env) {
+    if (!hasManagedIdentity(env))
+        return "public";
+    if (!env.YUI_ROLE || !env.YUI_NATIVE_SESSION_ID)
+        return "unbound";
+    if (env.YUI_SESSION_SCOPE === "global")
+        return env.YUI_ROLE === "operator" ? "operator" : "global";
+    if (env.YUI_SESSION_SCOPE === "task" && env.YUI_TASK_ID)
+        return env.YUI_ROLE === "leader" ? "leader" : "assignment";
+    return "unbound";
+}
+export function discoveryCommandTree(env) {
+    const audience = discoveryAudience(env);
+    const project = (node) => {
+        const children = node.children.map(project).filter((child) => child !== undefined);
+        const eligible = node.discovery?.surface !== "runtime" && node.discovery?.audiences.includes(audience);
+        if (!children.length && (!eligible || node.kind === "group") && node !== ROOT_COMMAND)
+            return undefined;
+        const executable = eligible && node.kind !== "group";
+        const kind = children.length ? executable ? "hybrid" : "group" : node.kind;
+        const template = `${node.path.join(" ")}${kind === "group" ? " <command>" : ""}`;
+        const omittedOptions = Object.entries(node.discovery?.optionAudiences ?? {})
+            .filter(([, audiences]) => !audiences.includes(audience)).map(([option]) => option);
+        const text = (value) => omittedOptions.reduce((line, option) => line.replace(new RegExp(`\\s*\\[${option}(?:\\s+[^\\]]*)?\\]`, "g"), ""), value);
+        const options = node.options.filter(option => !omittedOptions.includes(option));
+        // Group prose often contains concrete commands for several audiences.
+        // Generate its usage from the same retained children, not unfiltered text.
+        return {
+            ...node, children, hidden: false, kind,
+            usage: kind === "group" ? [template] : node.usage.map(text),
+            examples: kind === "group" ? children.slice(0, 3).map(child => child.usage[0]) : node.examples.map(text),
+            options, optionValues: Object.fromEntries(Object.entries(node.optionValues).filter(([option]) => options.includes(option))),
+            sections: node.sections.map(section => ({ ...section,
+                entries: section.entries.filter(entry => children.some(child => child.name === entry) || (executable && node.values.some(value => value.name === entry)))
+            })).filter(section => section.entries.length > 0),
+            ...(executable ? {} : { options: [], values: [], optionValues: {}, argumentValues: {} })
+        };
+    };
+    const tree = project(ROOT_COMMAND);
+    if (audience === "public") {
+        const sections = [
+            { id: "start", title: "Start work", entries: ["operator", "project"] },
+            { id: "progress", title: "Inspect progress", entries: ["task", "jobs", "execution", "telemetry"] },
+            { id: "participate", title: "Participate and control", entries: ["role", "session"] },
+            { id: "maintain", title: "Configure and maintain", entries: ["help", "version", "setup", "start", "doctor", "config", "web", "controller", "resources", "update", "upgrade", "release"] }
+        ];
+        return { ...tree, sections: sections.map(section => ({ ...section,
+                entries: section.entries.filter(entry => tree.children.some(child => child.name === entry))
+            })) };
+    }
+    // Help accepts catalog paths, and config describe accepts only retained domains.
+    const config = findCommandNode(["config"], tree);
+    if (config) {
+        const domains = config.children.filter(child => !["show", "describe"].includes(child.name)).map(child => child.name);
+        return {
+            ...tree, children: tree.children.map(child => child !== config ? child : {
+                ...config, children: config.children.map(node => node.name !== "describe" ? node : {
+                    ...node, argumentValues: { 0: domains }, usage: ["yui config describe [domain]"],
+                    examples: ["yui config describe"]
+                })
+            })
+        };
+    }
+    return tree;
+}

package/dist/cli/completion.js

@@ -1,235 +1,30 @@
-import { ROOT_COMMAND, listPublicCommandPaths, orderedImmediateTokens, visibleChildren } from "./commandCatalog.js";
-import { findInteractionPolicy } from "./interactionPolicy.js";
+/** Resolve the current caller on every completion, never the installer's view.
+ * Command names are local; target selectors use authenticated scoped reads. */
 export function renderCompletion(shell) {
-    const entries = collectEntries(ROOT_COMMAND);
     switch (shell) {
-        case "bash": return renderBash(entries);
-        case "zsh": return renderZsh(entries);
-        case "fish": return renderFish(entries);
-        default: throw new Error("Completion shell must be one of bash, zsh, fish.");
-    }
-}
-function collectEntries(root) {
-    const entries = [];
-    const visit = (node) => {
-        if (!node.hidden && !node.commandPathArguments) {
-            const policy = findInteractionPolicy(node);
-            entries.push({
-                path: node.path.slice(1).join(" "),
-                immediate: orderedImmediateTokens(node),
-                options: node.options,
-                dynamicArguments: policy?.selectors.flatMap((selector) => selector.argumentIndex === undefined ? [] : [selector.argumentIndex]) ?? [],
-                dynamicOptions: policy?.selectors.flatMap((selector) => selector.option === undefined ? [] : [selector.option]) ?? []
-            });
-        }
-        visibleChildren(node).forEach(visit);
-    };
-    visit(root);
-    return entries;
-}
-function manifest(prefix) {
-    return listPublicCommandPaths().map((path) => `${prefix} ${path}`).join("\n");
-}
-function renderBash(entries) {
-    const functionName = "_yui";
-    return `${manifest("# yui command:")}
-${functionName}() {
-  local current path previous dynamic_candidate dynamic=false
-  local -a candidates dynamic_candidates
-  current="\${COMP_WORDS[COMP_CWORD]}"
-  path=""
-  if (( COMP_CWORD > 1 )); then
-    path="\${COMP_WORDS[*]:1:COMP_CWORD-1}"
-  fi
-  previous="\${COMP_WORDS[COMP_CWORD-1]}"
-  if [[ "$current" != -* ]]; then
-    case "$COMP_CWORD:$path" in
-${bashDynamicArgumentCases(entries)}
-    esac
-  fi
-  if [[ "$dynamic" == false ]]; then
-    case "$previous:$path" in
-${bashDynamicOptionCases(entries)}
-    esac
-  fi
-  if [[ "$dynamic" == true ]]; then
-    while IFS= read -r dynamic_candidate; do
-      [[ -n "$dynamic_candidate" ]] && dynamic_candidates+=("$dynamic_candidate")
-    done < <(command yui config completion candidates "$current" -- "\${COMP_WORDS[@]:1:COMP_CWORD-1}" 2>/dev/null)
-    candidates=("\${dynamic_candidates[@]}")
-  elif [[ "$current" == -* ]]; then
-    case "$path" in
-${bashStaticOptionCases(entries)}
-      *) candidates=();;
-    esac
-  else
-    case "$path" in
-${entries.map((entry) => `      ${bashPattern(entry.path)}) candidates=(${[...entry.immediate, ...entry.options].map(shellQuote).join(" ")});;`).join("\n")}
-      *) candidates=();;
-    esac
-  fi
-  COMPREPLY=( $(compgen -W "\${candidates[*]}" -- "$current") )
-}
-complete -F ${functionName} yui
+        case "bash": return `_yui() {
+  local candidate current="\${COMP_WORDS[COMP_CWORD]}"
+  COMPREPLY=()
+  while IFS= read -r candidate; do
+    [[ -n "$candidate" ]] && COMPREPLY+=("$candidate")
+  done < <(command yui config completion candidates "$current" -- "\${COMP_WORDS[@]:1:COMP_CWORD-1}" 2>/dev/null)
+}
+complete -F _yui yui
 `;
-}
-function renderZsh(entries) {
-    return `#compdef yui
-${manifest("# yui command:")}
-local current command_path previous dynamic_output dynamic=false
+        case "zsh": return `#compdef yui
+local output
 local -a candidates
-current="$words[CURRENT]"
-command_path=""
-if (( CURRENT > 2 )); then
-  command_path="\${(j: :)words[2,CURRENT-1]}"
-fi
-previous="$words[CURRENT-1]"
-if [[ "$current" != -* ]]; then
-  case "$CURRENT:$command_path" in
-${zshDynamicArgumentCases(entries)}
-  esac
-fi
-if [[ "$dynamic" == false ]]; then
-  case "$previous:$command_path" in
-${zshDynamicOptionCases(entries)}
-  esac
-fi
-if [[ "$dynamic" == true ]]; then
-  dynamic_output="$(command yui config completion candidates "$current" -- "\${(@)words[2,CURRENT-1]}" 2>/dev/null)"
-  candidates=("\${(@f)dynamic_output}")
-elif [[ "$current" == -* ]]; then
-  case "$command_path" in
-${zshStaticOptionCases(entries)}
-    *) candidates=();;
-  esac
-else
-  case "$command_path" in
-${entries.map((entry) => `    ${zshPattern(entry.path)}) candidates=(${[...entry.immediate, ...entry.options].map(shellQuote).join(" ")});;`).join("\n")}
-    *) candidates=();;
-  esac
-fi
+output="$(command yui config completion candidates "$words[CURRENT]" -- "\${(@)words[2,CURRENT-1]}" 2>/dev/null)"
+candidates=("\${(@f)output}")
 (( \${#candidates[@]} > 0 )) && compadd -- "$candidates[@]"
 `;
-}
-function renderFish(entries) {
-    const prefix = "__yui";
-    const lines = [
-        manifest("# yui command:"),
-        `function ${prefix}_at_path`,
-        "  set -l actual (commandline -opc)",
-        "  set -e actual[1]",
-        "  test (count $actual) -eq (count $argv); or return 1",
-        "  for index in (seq (count $argv))",
-        "    test \"$actual[$index]\" = \"$argv[$index]\"; or return 1",
-        "  end",
-        "end",
-        `function ${prefix}_at_command_options`,
-        "  string match -q -- '-*' (commandline -ct); or return 1",
-        "  set -l actual (commandline -opc)",
-        "  set -e actual[1]",
-        "  test (count $actual) -ge (count $argv); or return 1",
-        "  for index in (seq (count $argv))",
-        "    test \"$actual[$index]\" = \"$argv[$index]\"; or return 1",
-        "  end",
-        "end",
-        `function ${prefix}_needs_dynamic`,
-        "  set -l mode $argv[1]",
-        "  set -l expected $argv[2]",
-        "  set -l expected_path $argv[3..-1]",
-        "  set -l actual (commandline -opc)",
-        "  set -e actual[1]",
-        "  test (count $actual) -ge (count $expected_path); or return 1",
-        "  for index in (seq (count $expected_path))",
-        "    test \"$actual[$index]\" = \"$expected_path[$index]\"; or return 1",
-        "  end",
-        "  if test \"$mode\" = argument",
-        "    string match -q -- '-*' (commandline -ct); and return 1",
-        "    test (count $actual) -eq \"$expected\"",
-        "  else",
-        "    test \"$actual[-1]\" = \"$expected\"",
-        "  end",
-        "end",
-        `function ${prefix}_dynamic`,
-        "  set -l words (commandline -opc)",
-        "  yui config completion candidates (commandline -ct) -- $words[2..-1] 2>/dev/null",
-        "end"
-    ];
-    for (const entry of entries) {
-        for (const argument of entry.dynamicArguments) {
-            const condition = `${prefix}_needs_dynamic argument ${argument} ${fishPath(entry.path)}`;
-            lines.push(`complete -c yui -f -n ${fishQuote(condition)} -a '(${prefix}_dynamic)'`);
-        }
-        for (const option of entry.dynamicOptions) {
-            const condition = `${prefix}_needs_dynamic option ${option} ${fishPath(entry.path)}`;
-            lines.push(`complete -c yui -f -n ${fishQuote(condition)} -a '(${prefix}_dynamic)'`);
-        }
-    }
-    for (const entry of entries) {
-        if (entry.immediate.length > 0) {
-            const condition = entry.path.length === 0
-                ? "__fish_use_subcommand"
-                : `${prefix}_at_path ${fishPath(entry.path)}${fishInitialDynamicExclusion(entry, prefix)}`;
-            lines.push(`complete -c yui -f -n ${fishQuote(condition)} -a '${escapeSingle(entry.immediate.join(" "))}'`);
-        }
-        if (entry.options.length > 0) {
-            const path = fishPath(entry.path);
-            const exact = `${prefix}_at_path ${path}${fishInitialDynamicExclusion(entry, prefix)}`;
-            const condition = `begin; ${exact}; end; or ${prefix}_at_command_options ${path}`;
-            lines.push(`complete -c yui -f -n ${fishQuote(condition)} -a '${escapeSingle(entry.options.join(" "))}'`);
-        }
+        case "fish": return `function __yui_candidates
+  set -l words (commandline -opc)
+  set -l current (commandline -ct)
+  command yui config completion candidates "$current" -- $words[2..-1] 2>/dev/null
+end
+complete -c yui -f -a '(__yui_candidates)'
+`;
+        default: throw new Error("Completion shell must be one of bash, zsh, fish.");
     }
-    return `${lines.join("\n")}\n`;
-}
-function bashDynamicArgumentCases(entries) {
-    return entries.flatMap((entry) => entry.dynamicArguments.map((argument) => `    ${dynamicArgumentPattern(argument + 1, entry.path)}) dynamic=true;;`)).join("\n");
-}
-function zshDynamicArgumentCases(entries) {
-    return entries.flatMap((entry) => entry.dynamicArguments.map((argument) => `  ${dynamicArgumentPattern(argument + 2, entry.path)}) dynamic=true;;`)).join("\n");
-}
-function dynamicArgumentPattern(position, path) {
-    return `${position}:${shellQuote(path)}|${position}:${shellQuote(`${path} `)}*`;
-}
-function bashDynamicOptionCases(entries) {
-    return entries.flatMap((entry) => entry.dynamicOptions.map((option) => `      ${dynamicOptionPattern(option, entry.path)}) dynamic=true;;`)).join("\n");
-}
-function zshDynamicOptionCases(entries) {
-    return entries.flatMap((entry) => entry.dynamicOptions.map((option) => `    ${dynamicOptionPattern(option, entry.path)}) dynamic=true;;`)).join("\n");
-}
-function dynamicOptionPattern(option, path) {
-    return `${shellQuote(`${option}:${path}`)}|${shellQuote(`${option}:${path} `)}*`;
-}
-function bashStaticOptionCases(entries) {
-    return staticOptionEntries(entries).map((entry) => `      ${commandPrefixPattern(entry.path)}) candidates=(${entry.options.map(shellQuote).join(" ")});;`).join("\n");
-}
-function zshStaticOptionCases(entries) {
-    return staticOptionEntries(entries).map((entry) => `    ${commandPrefixPattern(entry.path)}) candidates=(${entry.options.map(shellQuote).join(" ")});;`).join("\n");
-}
-function staticOptionEntries(entries) {
-    return entries.filter((entry) => entry.options.length > 0)
-        .sort((left, right) => right.path.split(" ").length - left.path.split(" ").length);
-}
-function commandPrefixPattern(path) {
-    return `${shellQuote(path)}|${shellQuote(`${path} `)}*`;
-}
-function fishInitialDynamicExclusion(entry, prefix) {
-    const initial = entry.dynamicArguments.filter((position) => position === entry.path.split(" ").filter(Boolean).length);
-    return initial.map((position) => `; and not ${prefix}_needs_dynamic argument ${position} ${fishPath(entry.path)}`).join("");
-}
-function fishPath(path) {
-    return path.split(" ").filter(Boolean).join(" ");
-}
-function bashPattern(path) {
-    return path.length === 0 ? '""' : shellQuote(path);
-}
-function zshPattern(path) {
-    return path.length === 0 ? '""' : shellQuote(path);
-}
-function shellQuote(value) {
-    return `'${escapeSingle(value)}'`;
-}
-function fishQuote(value) {
-    return `'${escapeSingle(value)}'`;
-}
-function escapeSingle(value) {
-    return value.replaceAll("'", "'\\''");
 }

package/dist/cli/dynamicCompletion.js

@@ -5,7 +5,16 @@ export async function resolveCompletionCandidates(input) {
     const words = input.words[0] === "yui"
         ? input.words.slice(1)
         : [...input.words];
-    const { node, consumed } = resolveCommand(words);
+    const root = input.root ?? ROOT_COMMAND;
+    if (words[0] === "help") {
+        const { node, consumed } = resolveCommand(words.slice(1), root);
+        return consumed === words.length - 1 ? prefix(visibleChildren(node).map(child => child.name), input.current) : [];
+    }
+    const { node, consumed } = resolveCommand(words, root);
+    if (node.kind === "group" && consumed < words.length)
+        return [];
+    if (input.current.startsWith("-"))
+        return prefix(node.options, input.current);
     if (consumed === words.length && node.children.length > 0) {
         return prefix(visibleChildren(node).map((child) => child.name), input.current);
     }
@@ -13,9 +22,6 @@ export async function resolveCompletionCandidates(input) {
     if (previous !== undefined && Object.hasOwn(node.optionValues, previous)) {
         return prefix(node.optionValues[previous] ?? [], input.current);
     }
-    if (input.current.startsWith("-")) {
-        return prefix(node.options, input.current);
-    }
     const argumentPosition = words.length;
     const policy = findInteractionPolicy(node);
     const selector = policy?.selectors.find((candidate) => selectorApplies(candidate, previous, argumentPosition));
@@ -31,8 +37,8 @@ function selectorApplies(selector, previous, argumentPosition) {
         return selector.option === previous;
     return selector.argumentIndex === argumentPosition;
 }
-function resolveCommand(words) {
-    let node = ROOT_COMMAND;
+function resolveCommand(words, root) {
+    let node = root;
     let consumed = 0;
     while (consumed < words.length && node.kind !== "leaf") {
         const child = findChild(node, words[consumed] ?? "");

package/dist/cli/invocationAuthority.js

@@ -1,4 +1,5 @@
 import { usageError } from "../errors/cliError.js";
+import { hasManagedIdentity } from "../runtime/managedIdentity.js";
 import { requireManagedGlobalCaller } from "../runtime/managedCaller.js";
 import { routeInvocation } from "./invocationRouter.js";
 import { findInteractionPolicy } from "./interactionPolicy.js";
@@ -17,8 +18,7 @@ export function assertConfigurationAuthority(args, store, env) {
         requireManagedGlobalCaller(store, env);
         return;
     }
-    if (env.YUI_SESSION_SCOPE !== undefined || env.YUI_ROLE !== undefined
-        || env.YUI_AGENT_ID !== undefined || env.YUI_NATIVE_SESSION_ID !== undefined) {
+    if (hasManagedIdentity(env)) {
         throw usageError("Home configuration and resource mutations require the user or current Operator, not a Task Assignment.");
     }
 }

package/dist/cli/invocationRouter.js

@@ -1,16 +1,27 @@
 import { findChild, ROOT_COMMAND } from "./commandCatalog.js";
-export function routeInvocation(args) {
+export function routeInvocation(args, discoveryRoot = ROOT_COMMAND) {
     if (args.length === 0)
         return { kind: "execute", node: ROOT_COMMAND };
     if (args[0] === "help")
-        return resolveHelpPath(args.slice(1));
-    return resolveExecutionPath(args);
+        return resolveHelpPath(args.slice(1), discoveryRoot);
+    const result = resolveExecutionPath(args);
+    if (result.kind === "execute" || result.kind === "help")
+        return result;
+    const path = result.helpNode.path.slice(1);
+    let helpNode = discoveryRoot;
+    for (const segment of path) {
+        const child = findChild(helpNode, segment);
+        if (!child)
+            break;
+        helpNode = child;
+    }
+    return { ...result, helpNode };
 }
-function resolveHelpPath(path) {
+function resolveHelpPath(path, root) {
     if (path.length === 0)
-        return { kind: "help", node: ROOT_COMMAND };
-    let node = ROOT_COMMAND;
-    let nearestGroup = ROOT_COMMAND;
+        return { kind: "help", node: root };
+    let node = root;
+    let nearestGroup = root;
     for (const segment of path) {
         const child = findChild(node, segment);
         if (child === undefined || child.hidden) {

package/dist/cli/managedDiagnostics.js

@@ -4,7 +4,7 @@ export function taskDiagnosticTarget(args) {
     if (args[0] !== "task")
         return undefined;
     if (["show", "context", "next-action", "archive-preflight"].includes(args[1] ?? "")) {
-        return args[1] === "context" && ["read", "inspect", "delta"].includes(args[2] ?? "")
+        return args[1] === "context" && ["read", "list", "inspect", "delta"].includes(args[2] ?? "")
             ? args[3] : args[2];
     }
     if (args[1] === "role" && ["list", "status", "show"].includes(args[2] ?? ""))
@@ -23,6 +23,7 @@ export function operatorOfflineCommand(args) {
         || (args[0] === "execution" && args[1] === "audit")
         || (args[0] === "operator" && ["status", "list"].includes(args[1] ?? ""))
         || (args[0] === "session" && ["context", "reconcile"].includes(args[1] ?? ""))
+        || (args[0] === "role" && args[1] === "message" && ["list", "show"].includes(args[2] ?? ""))
         || (args[0] === "task" && args[1] === "list")
         || taskDiagnosticTarget(args) !== undefined;
 }

package/dist/cli/updatePorts.js

@@ -203,11 +203,6 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
                     + `but the staged/verified artifact was ${staged.version}. Refusing to trust a `
                     + "different build than the one that passed preflight.");
             }
-            // Retarget current Manifest-referenced wrappers to the activated
-            // installation before the replacement Controller starts. This relocates
-            // the current shell form; it does not convert historical Session wrappers.
-            const sessionCliRefresh = run(activeBinary, ["--json", "internal", "session-cli-refresh"], { cwd: process.cwd(), env: { ...environment, YUI_HOME: home }, shell: false });
-            assertSpawnOk(sessionCliRefresh, "refresh managed Session CLI wrappers");
             // Retain the exact path used by both doctor and version verification. The
             // replacement start must not resolve UPDATE_CLI_PATH or npm again.
             verifiedActivatedBinary = activeBinary;