@zq-silk/yui 0.0.0

package/dist/cli/interactionPolicy.js

@@ -0,0 +1,389 @@
+const taskTarget = (command, argumentIndex = 2, statuses) => ({
+    commandPath: ["task", command],
+    selectors: [{
+            argumentIndex,
+            entity: "task",
+            provider: "tasks",
+            actionTarget: true,
+            ...(statuses === undefined ? {} : { statuses })
+        }]
+});
+export const INTERACTION_POLICIES = Object.freeze([
+    ...["show", "update", "remove"].map((command) => ({
+        commandPath: ["agent", command],
+        selectors: [{
+                argumentIndex: 2,
+                entity: "agent",
+                provider: "configured-agents",
+                actionTarget: true
+            }],
+        ...(command === "remove"
+            ? { confirmation: { action: "Remove Agent", targetArgumentIndex: 2 } }
+            : {})
+    })),
+    {
+        commandPath: ["role", "add"],
+        selectors: [{
+                option: "--agent",
+                requiredOption: true,
+                entity: "agent",
+                provider: "configured-agents",
+                actionTarget: false
+            }],
+        trailingOptions: {
+            "--agent": "value", "--workspace": "value", "--description": "value",
+            "--responsibility": "value", "--constraint": "value", "--expected-output": "value",
+            "--system-prompt": "value", "--skill": "value", "--model": "value",
+            "--effort": "value", "--sandbox": "value", "--approval": "value",
+            "--permission-mode": "value", "--search": "value"
+        }
+    },
+    ...["show", "update", "remove", "enter"].map((command) => ({
+        commandPath: ["role", command],
+        selectors: [{
+                argumentIndex: 2,
+                entity: "global-role",
+                provider: "global-roles",
+                actionTarget: true
+            }],
+        ...(command === "remove"
+            ? { confirmation: { action: "Remove Role", targetArgumentIndex: 2 } }
+            : {})
+    })),
+    {
+        commandPath: ["role", "bind"],
+        selectors: [
+            { argumentIndex: 2, entity: "global-role", provider: "global-roles", actionTarget: true },
+            { argumentIndex: 3, entity: "agent", provider: "configured-agents", actionTarget: false }
+        ]
+    },
+    ...["record", "replace"].map((command) => ({
+        commandPath: ["role", "session", command],
+        selectors: [{
+                argumentIndex: 3,
+                entity: "global-role",
+                provider: "global-roles",
+                actionTarget: true
+            }],
+        trailingOptions: command === "replace"
+            ? { "--native-id": "value", "--reason": "value" }
+            : { "--native-id": "value" }
+    })),
+    taskTarget("show"),
+    taskTarget("context"),
+    {
+        ...taskTarget("update"),
+        trailingOptions: {
+            "--title": "value",
+            "--description": "value",
+            "--priority": "value",
+            "--tags": "value",
+            "--due-at": "value",
+            "--clear-description": "flag",
+            "--clear-priority": "flag",
+            "--clear-tags": "flag",
+            "--clear-due-at": "flag"
+        }
+    },
+    taskTarget("activate", 2, ["draft"]),
+    {
+        ...taskTarget("complete", 2, ["active"]),
+        trailingOptions: { "--summary": "value" }
+    },
+    taskTarget("reopen", 2, ["completed"]),
+    {
+        ...taskTarget("archive"),
+        confirmation: { action: "Archive task", targetArgumentIndex: 2 }
+    },
+    taskTarget("reconcile"),
+    {
+        commandPath: ["operator", "submit"],
+        selectors: [{
+                option: "--task",
+                entity: "task",
+                provider: "tasks",
+                actionTarget: false
+            }],
+        trailingOptions: { "--task": "value" }
+    },
+    {
+        commandPath: ["task", "create"],
+        selectors: [{
+                option: "--repository",
+                entity: "repository",
+                provider: "repositories",
+                actionTarget: false
+            }],
+        trailingOptions: { "--repository": "value", "--base": "value" }
+    },
+    ...["send", "list"].map((command) => ({
+        commandPath: ["task", "message", command],
+        selectors: [{
+                argumentIndex: 3,
+                entity: "task",
+                provider: "tasks",
+                actionTarget: true
+            }]
+    })),
+    {
+        commandPath: ["task", "input", "request"],
+        selectors: [{
+                argumentIndex: 3,
+                entity: "task",
+                provider: "tasks",
+                actionTarget: true,
+                statuses: ["active"]
+            }],
+        trailingOptions: {
+            "--question": "value",
+            "--choice": "value",
+            "--blocks": "value",
+            "--recommend": "value",
+            "--timeout-seconds": "value"
+        }
+    },
+    {
+        commandPath: ["task", "input", "show"],
+        selectors: [
+            { argumentIndex: 3, entity: "input-request", provider: "input-requests", actionTarget: true },
+            { option: "--task", entity: "task", provider: "tasks", actionTarget: false }
+        ],
+        trailingOptions: { "--task": "value" }
+    },
+    {
+        commandPath: ["task", "input", "answer"],
+        selectors: [
+            {
+                argumentIndex: 3,
+                entity: "input-request",
+                provider: "input-requests",
+                actionTarget: true,
+                statuses: ["open"]
+            },
+            { option: "--task", entity: "task", provider: "tasks", actionTarget: false }
+        ],
+        trailingOptions: { "--task": "value", "--choice": "value", "--text": "value" }
+    },
+    {
+        commandPath: ["task", "input", "cancel"],
+        selectors: [
+            {
+                argumentIndex: 3,
+                entity: "task",
+                provider: "tasks",
+                actionTarget: true,
+                statuses: ["active"]
+            },
+            {
+                argumentIndex: 4,
+                entity: "input-request",
+                provider: "input-requests",
+                dependsOn: 3,
+                actionTarget: true,
+                statuses: ["open"]
+            }
+        ],
+        trailingOptions: { "--reason": "value" }
+    },
+    {
+        commandPath: ["task", "role", "add"],
+        selectors: [
+            { argumentIndex: 3, entity: "task", provider: "tasks", actionTarget: true },
+            { option: "--agent", entity: "agent", provider: "configured-agents", actionTarget: false }
+        ],
+        trailingOptions: {
+            "--agent": "value", "--description": "value", "--responsibility": "value",
+            "--constraint": "value", "--expected-output": "value", "--system-prompt": "value",
+            "--skill": "value", "--model": "value", "--effort": "value",
+            "--sandbox": "value", "--approval": "value", "--permission-mode": "value",
+            "--search": "value"
+        }
+    },
+    {
+        commandPath: ["task", "role", "list"],
+        selectors: [{ argumentIndex: 3, entity: "task", provider: "tasks", actionTarget: true }]
+    },
+    ...["show", "status", "update", "remove"].map((command) => ({
+        commandPath: ["task", "role", command],
+        selectors: [
+            { argumentIndex: 3, entity: "task", provider: "tasks", actionTarget: true },
+            {
+                argumentIndex: 4,
+                entity: "task-role",
+                provider: "task-roles",
+                dependsOn: 3,
+                actionTarget: true
+            }
+        ],
+        ...(command === "remove"
+            ? { confirmation: { action: "Remove Task Role", targetArgumentIndex: 4 } }
+            : {})
+    })),
+    {
+        commandPath: ["task", "role", "bind"],
+        selectors: [
+            { argumentIndex: 3, entity: "task", provider: "tasks", actionTarget: true },
+            {
+                argumentIndex: 4,
+                entity: "task-role",
+                provider: "task-roles",
+                dependsOn: 3,
+                actionTarget: true
+            },
+            { argumentIndex: 5, entity: "agent", provider: "configured-agents", actionTarget: false }
+        ]
+    },
+    {
+        commandPath: ["task", "role", "enter"],
+        selectors: [
+            { argumentIndex: 3, entity: "task", provider: "tasks", actionTarget: true },
+            {
+                argumentIndex: 4,
+                entity: "task-role",
+                provider: "task-roles",
+                dependsOn: 3,
+                actionTarget: true
+            }
+        ]
+    },
+    {
+        commandPath: ["task", "work", "create"],
+        selectors: [
+            { argumentIndex: 3, entity: "task", provider: "tasks", actionTarget: true },
+            {
+                option: "--role",
+                entity: "task-role",
+                provider: "task-roles",
+                dependsOn: 3,
+                actionTarget: false
+            }
+        ],
+        trailingOptions: { "--role": "value" }
+    },
+    {
+        commandPath: ["task", "work", "list"],
+        selectors: [{ argumentIndex: 3, entity: "task", provider: "tasks", actionTarget: true }]
+    },
+    {
+        commandPath: ["task", "work", "update"],
+        selectors: [{ argumentIndex: 3, entity: "work-item", provider: "work-items", actionTarget: true }],
+        trailingOptions: { "--summary": "value" }
+    },
+    {
+        commandPath: ["task", "work", "dispatch"],
+        selectors: [{ argumentIndex: 3, entity: "work-item", provider: "work-items", actionTarget: true }],
+        trailingOptions: { "--input": "value" }
+    },
+    {
+        commandPath: ["task", "run", "list"],
+        selectors: [{ argumentIndex: 3, entity: "work-item", provider: "work-items", actionTarget: true }]
+    },
+    ...["retry", "yield"].map((command) => ({
+        commandPath: ["task", "run", command],
+        selectors: [{ argumentIndex: 3, entity: "run", provider: "runs", actionTarget: true }],
+        ...(command === "yield" ? { trailingOptions: { "--summary": "value" } } : {})
+    })),
+    {
+        commandPath: ["task", "enter"],
+        selectors: [{ argumentIndex: 2, entity: "task", provider: "tasks", actionTarget: true }]
+    },
+    {
+        commandPath: ["jobs", "retry"],
+        selectors: [{ argumentIndex: 2, entity: "job", provider: "jobs", actionTarget: true }]
+    },
+    ...[
+        ["brief", "show"],
+        ["brief", "update"],
+        ["decision", "record"],
+        ["decision", "list"],
+        ["decision", "show"],
+        ["decision", "supersede"],
+        ["milestone", "add"],
+        ["milestone", "list"],
+        ["milestone", "show"],
+        ["event", "list"],
+        ["event", "show"]
+    ].map(([group, command]) => {
+        const trailingOptions = {};
+        if (group === "brief" && command === "update") {
+            Object.assign(trailingOptions, { "--objective": "value", "--boundary": "value", "--focus": "value", "--leader-summary": "value" });
+        }
+        else if (group === "decision" && command === "record") {
+            Object.assign(trailingOptions, { "--title": "value", "--rationale": "value" });
+        }
+        else if (group === "decision" && command === "list") {
+            Object.assign(trailingOptions, { "--status": "value" });
+        }
+        else if (group === "decision" && command === "supersede") {
+            Object.assign(trailingOptions, { "--reason": "value" });
+        }
+        else if (group === "milestone" && command === "add") {
+            Object.assign(trailingOptions, { "--title": "value", "--summary": "value" });
+        }
+        const mutatesKnowledge = (group === "brief" && command === "update")
+            || (group === "decision" && (command === "record" || command === "supersede"))
+            || (group === "milestone" && command === "add");
+        const selectors = [{
+                argumentIndex: 3,
+                entity: "task",
+                provider: "tasks",
+                actionTarget: true,
+                ...(mutatesKnowledge ? { statuses: ["draft", "active"] } : {})
+            }];
+        if (group === "decision" && (command === "show" || command === "supersede")) {
+            selectors.push({
+                argumentIndex: 4,
+                entity: "decision",
+                provider: "task-decisions",
+                dependsOn: 3,
+                actionTarget: true,
+                ...(command === "supersede" ? { statuses: ["active"] } : {})
+            });
+        }
+        else if (group === "milestone" && command === "show") {
+            selectors.push({
+                argumentIndex: 4,
+                entity: "milestone",
+                provider: "task-milestones",
+                dependsOn: 3,
+                actionTarget: true
+            });
+        }
+        else if (group === "event" && command === "show") {
+            selectors.push({
+                argumentIndex: 4,
+                entity: "event",
+                provider: "task-events",
+                dependsOn: 3,
+                actionTarget: true
+            });
+        }
+        return {
+            commandPath: ["task", group, command],
+            selectors,
+            ...(Object.keys(trailingOptions).length > 0 ? { trailingOptions } : {})
+        };
+    })
+]);
+export function findInteractionPolicy(node) {
+    if (node === undefined)
+        return undefined;
+    const path = node.path.slice(1);
+    return INTERACTION_POLICIES.find((policy) => policy.commandPath.length === path.length
+        && policy.commandPath.every((segment, index) => segment === path[index]));
+}
+export function validateInteractionPolicies(policies = INTERACTION_POLICIES) {
+    const paths = new Set();
+    for (const policy of policies) {
+        const path = policy.commandPath.join(" ");
+        if (paths.has(path))
+            throw new Error(`Duplicate interaction policy: ${path}`);
+        paths.add(path);
+        for (const selector of policy.selectors) {
+            if ((selector.argumentIndex === undefined) === (selector.option === undefined)) {
+                throw new Error(`Interaction selector must declare exactly one slot: ${path}`);
+            }
+        }
+    }
+}
+validateInteractionPolicies();

package/dist/cli/interactiveSelection.js

@@ -0,0 +1,185 @@
+import { renderTable } from "../output/table.js";
+import { getSelectionCandidates } from "./interactionCandidates.js";
+import { findInteractionPolicy } from "./interactionPolicy.js";
+export async function resolveInteractiveArguments(args, node, ports, io) {
+    const resolved = [...args];
+    if (!io.interactive || !allowsInteractiveSelection(args, io.json)) {
+        return { kind: "unchanged", args: resolved };
+    }
+    const policy = findInteractionPolicy(node);
+    if (hasUnknownOption(resolved, node) || !interactionPrerequisitesReady(resolved, node, policy)) {
+        return { kind: "unchanged", args: resolved };
+    }
+    let changed = false;
+    let selectedActionTarget = false;
+    if (policy !== undefined) {
+        for (const selector of policy.selectors) {
+            const slot = missingSlot(resolved, selector, node);
+            if (slot === undefined)
+                continue;
+            const candidates = await getSelectionCandidates(selector, ports, resolved);
+            if (candidates === null)
+                continue;
+            const selected = await selectCandidate(candidates, io);
+            if (selected === undefined)
+                return { kind: "cancelled", args: resolved };
+            if (slot.kind === "argument") {
+                resolved.splice(slot.index, 0, selected.value);
+            }
+            else if (slot.optionPresent) {
+                resolved.splice(slot.index + 1, 0, selected.value);
+            }
+            else {
+                resolved.push(slot.option, selected.value);
+            }
+            changed = true;
+            selectedActionTarget ||= selector.actionTarget;
+        }
+    }
+    const enumResult = await resolveCatalogEnums(resolved, node, io);
+    if (enumResult === "cancelled")
+        return { kind: "cancelled", args: resolved };
+    changed ||= enumResult === "resolved";
+    if (selectedActionTarget && policy?.confirmation !== undefined) {
+        const target = resolved[policy.confirmation.targetArgumentIndex] ?? "";
+        const answer = (await io.question(`${policy.confirmation.action} ${target}? [y/N]: `))?.trim().toLowerCase();
+        if (answer !== "y" && answer !== "yes") {
+            return { kind: "cancelled", args: resolved };
+        }
+    }
+    return changed
+        ? { kind: "resolved", args: resolved }
+        : { kind: "unchanged", args: resolved };
+}
+export function allowsInteractiveSelection(args, globalJson) {
+    return !globalJson && !args.includes("--json")
+        && !(args[0] === "completion" && args[1] === "candidates");
+}
+function missingSlot(args, selector, node) {
+    if (selector.argumentIndex !== undefined) {
+        const value = args[selector.argumentIndex];
+        return value === undefined || value.startsWith("--")
+            ? { kind: "argument", index: selector.argumentIndex }
+            : undefined;
+    }
+    const option = selector.option;
+    if (option === undefined)
+        return undefined;
+    const index = args.indexOf(option);
+    if (index < 0) {
+        return selector.requiredOption === true
+            ? { kind: "option", option, index: args.length, optionPresent: false }
+            : undefined;
+    }
+    const value = args[index + 1];
+    if (value !== undefined && !value.startsWith("--"))
+        return undefined;
+    if (!node.options.includes(option))
+        return undefined;
+    return { kind: "option", option, index, optionPresent: true };
+}
+function hasUnknownOption(args, node) {
+    const known = new Set([...node.options, "--json"]);
+    return args.some((argument) => argument.startsWith("-") && !known.has(argument));
+}
+function interactionPrerequisitesReady(args, node, policy) {
+    const usage = node.usage[0] ?? "";
+    const required = usage.replaceAll(/\[[^\]]*\]/g, "").trim().split(/\s+/);
+    const tail = required.slice(node.path.length);
+    let position = 0;
+    for (let index = 0; index < tail.length; index += 1) {
+        const token = tail[index] ?? "";
+        if (token.startsWith("--")) {
+            const optionIndex = args.indexOf(token);
+            const next = tail[index + 1];
+            if (optionIndex < 0)
+                return false;
+            if (next?.startsWith("<") === true) {
+                const value = args[optionIndex + 1];
+                if (value === undefined || value.startsWith("--"))
+                    return false;
+                index += 1;
+            }
+            continue;
+        }
+        if (!token.startsWith("<") || !token.endsWith(">"))
+            continue;
+        const absoluteIndex = node.path.length - 1 + position;
+        const value = args[absoluteIndex];
+        const selectable = policy?.selectors.some((selector) => selector.argumentIndex === absoluteIndex) === true
+            || Object.hasOwn(node.argumentValues, position);
+        if ((value === undefined || value.startsWith("--")) && !selectable)
+            return false;
+        position += 1;
+    }
+    for (const option of node.options) {
+        const optionIndex = args.indexOf(option);
+        if (optionIndex < 0)
+            continue;
+        const value = args[optionIndex + 1];
+        const selectable = policy?.selectors.some((selector) => selector.option === option) === true
+            || Object.hasOwn(node.optionValues, option);
+        if ((value === undefined || value.startsWith("--")) && !selectable)
+            return false;
+    }
+    return true;
+}
+async function resolveCatalogEnums(args, node, io) {
+    let changed = false;
+    const argumentBase = node.path.length - 1;
+    for (const [relativeText, choices] of Object.entries(node.argumentValues)) {
+        const index = argumentBase + Number(relativeText);
+        const value = args[index];
+        if (value !== undefined && !value.startsWith("--"))
+            continue;
+        const selected = await selectValues(`Select value`, choices, io);
+        if (selected === undefined)
+            return "cancelled";
+        args.splice(index, 0, selected);
+        changed = true;
+    }
+    for (const [option, choices] of Object.entries(node.optionValues)) {
+        const index = args.indexOf(option);
+        if (index < 0)
+            continue;
+        const value = args[index + 1];
+        if (value !== undefined && !value.startsWith("--"))
+            continue;
+        const selected = await selectValues(`Select ${option.slice(2)}`, choices, io);
+        if (selected === undefined)
+            return "cancelled";
+        args.splice(index + 1, 0, selected);
+        changed = true;
+    }
+    return changed ? "resolved" : "unchanged";
+}
+async function selectValues(title, values, io) {
+    return (await selectCandidate({
+        entityLabel: "value",
+        title,
+        columns: [{ header: "Value", minWidth: 5, maxWidth: 32 }],
+        candidates: values.map((value) => ({ value, cells: [value] })),
+        emptyMessage: "No values are available.",
+        overflowHint: "Pass the value explicitly."
+    }, io))?.value;
+}
+async function selectCandidate(set, io) {
+    if (set.candidates.length === 0) {
+        io.write(`○ ${set.emptyMessage}\n`);
+        return undefined;
+    }
+    io.write(`${renderTable(set.title, [{ header: "#", minWidth: 1, maxWidth: 4 }, ...set.columns], set.candidates.map((candidate, index) => [String(index + 1), ...candidate.cells]), io.width)}\n\n`);
+    const answer = (await io.question(`Choose ${set.entityLabel} [1-${set.candidates.length}/value, q]: `))?.trim();
+    if (answer === undefined || answer.toLowerCase() === "q" || answer.toLowerCase() === "quit") {
+        return undefined;
+    }
+    if (answer.length === 0) {
+        return set.candidates.find((candidate) => candidate.value === set.defaultValue)
+            ?? set.candidates[0];
+    }
+    const numeric = Number(answer);
+    if (Number.isSafeInteger(numeric) && numeric >= 1 && numeric <= set.candidates.length) {
+        return set.candidates[numeric - 1];
+    }
+    return set.candidates.find((candidate) => candidate.value === answer);
+}

package/dist/cli/invocationRouter.js

@@ -0,0 +1,51 @@
+import { findChild, ROOT_COMMAND } from "./commandCatalog.js";
+export function routeInvocation(args) {
+    if (args.length === 0)
+        return { kind: "execute", node: ROOT_COMMAND };
+    if (args[0] === "help")
+        return resolveHelpPath(args.slice(1));
+    return resolveExecutionPath(args);
+}
+function resolveHelpPath(path) {
+    if (path.length === 0)
+        return { kind: "help", node: ROOT_COMMAND };
+    let node = ROOT_COMMAND;
+    let nearestGroup = ROOT_COMMAND;
+    for (const segment of path) {
+        const child = findChild(node, segment);
+        if (child === undefined || child.hidden) {
+            return { kind: "path-error", typedPath: path.join(" "), helpNode: nearestGroup };
+        }
+        node = child;
+        if (node.kind !== "leaf")
+            nearestGroup = node;
+    }
+    return { kind: "help", node };
+}
+function resolveExecutionPath(args) {
+    let node = ROOT_COMMAND;
+    let nearestGroup = ROOT_COMMAND;
+    let index = 0;
+    while (index < args.length) {
+        if (node.kind === "leaf")
+            break;
+        const child = findChild(node, args[index] ?? "");
+        if (child === undefined) {
+            if (node.kind === "hybrid" && node.acceptsArguments)
+                break;
+            return {
+                kind: "path-error",
+                typedPath: args.slice(0, index + 1).join(" "),
+                helpNode: nearestGroup
+            };
+        }
+        node = child;
+        index += 1;
+        if (node.kind !== "leaf")
+            nearestGroup = node;
+    }
+    if (node.kind === "group" && index === args.length) {
+        return { kind: "incomplete", typedPath: args.join(" "), helpNode: node };
+    }
+    return { kind: "execute", node };
+}