@timurproko/a1 0.1.8-dev.ece8cef → 0.2.1-dev.590

package/dist/app/session-shell/stream-presentation-coalescer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 33 ms (30.3 fps): baseline chunks arrive every 5 ms, while this cadence
+ * retains immediate first paint/input and explicit final-state flushing.
+ */
+export declare const STREAM_PRESENTATION_INTERVAL_MS = 33;
+export interface StreamPresentationScheduler {
+    now(): number;
+    setTimeout(callback: () => void, delayMs: number): ReturnType<typeof setTimeout>;
+    clearTimeout(timer: ReturnType<typeof setTimeout>): void;
+}
+/** Bounds terminal presentation requests while semantic root state remains current. */
+export declare class StreamPresentationCoalescer {
+    #private;
+    readonly present: () => void;
+    readonly intervalMs: number;
+    readonly scheduler: StreamPresentationScheduler;
+    constructor(present: () => void, intervalMs?: number, scheduler?: StreamPresentationScheduler);
+    get pending(): boolean;
+    request(): void;
+    /** Cancels a superseded stream frame; the immediate input/overlay/resize path renders current state. */
+    preempt(): void;
+    /** Records an immediate input/status/overlay frame and cancels an obsolete stream timer. */
+    noteImmediatePresentation(): void;
+    /** Presents current semantic state immediately regardless of pending stream work. */
+    presentImmediate(): void;
+    /** Presents the newest semantic state immediately only when a stream frame is pending. */
+    flush(): void;
+    dispose(): void;
+}

package/dist/app/session-shell/stream-presentation-coalescer.js

@@ -0,0 +1,79 @@
+/**
+ * 33 ms (30.3 fps): baseline chunks arrive every 5 ms, while this cadence
+ * retains immediate first paint/input and explicit final-state flushing.
+ */
+export const STREAM_PRESENTATION_INTERVAL_MS = 33;
+const SYSTEM_SCHEDULER = {
+    now: Date.now,
+    setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+    clearTimeout: timer => clearTimeout(timer),
+};
+/** Bounds terminal presentation requests while semantic root state remains current. */
+export class StreamPresentationCoalescer {
+    #timer;
+    #lastPresentationAt = Number.NEGATIVE_INFINITY;
+    #disposed = false;
+    present;
+    intervalMs;
+    scheduler;
+    constructor(present, intervalMs = STREAM_PRESENTATION_INTERVAL_MS, scheduler = SYSTEM_SCHEDULER) {
+        this.present = present;
+        this.intervalMs = intervalMs;
+        this.scheduler = scheduler;
+        if (!Number.isSafeInteger(intervalMs) || intervalMs < 1)
+            throw new RangeError("stream presentation interval must be positive");
+    }
+    get pending() { return this.#timer !== undefined; }
+    request() {
+        if (this.#disposed || this.#timer !== undefined)
+            return;
+        const elapsed = this.scheduler.now() - this.#lastPresentationAt;
+        if (elapsed >= this.intervalMs) {
+            this.#presentNow();
+            return;
+        }
+        this.#timer = this.scheduler.setTimeout(() => {
+            this.#timer = undefined;
+            this.#presentNow();
+        }, Math.max(0, this.intervalMs - elapsed));
+    }
+    /** Cancels a superseded stream frame; the immediate input/overlay/resize path renders current state. */
+    preempt() {
+        if (this.#timer === undefined)
+            return;
+        this.scheduler.clearTimeout(this.#timer);
+        this.#timer = undefined;
+    }
+    /** Records an immediate input/status/overlay frame and cancels an obsolete stream timer. */
+    noteImmediatePresentation() {
+        if (this.#disposed)
+            return;
+        this.preempt();
+        this.#lastPresentationAt = this.scheduler.now();
+    }
+    /** Presents current semantic state immediately regardless of pending stream work. */
+    presentImmediate() {
+        if (this.#disposed)
+            return;
+        this.noteImmediatePresentation();
+        this.present();
+    }
+    /** Presents the newest semantic state immediately only when a stream frame is pending. */
+    flush() {
+        if (this.#disposed || this.#timer === undefined)
+            return;
+        this.scheduler.clearTimeout(this.#timer);
+        this.#timer = undefined;
+        this.#presentNow();
+    }
+    dispose() {
+        this.preempt();
+        this.#disposed = true;
+    }
+    #presentNow() {
+        if (this.#disposed)
+            return;
+        this.#lastPresentationAt = this.scheduler.now();
+        this.present();
+    }
+}

package/dist/app/session-shell/system-clipboard.d.ts

@@ -0,0 +1,20 @@
+import type { PiShellClipboardContent } from "../../integrations/pi/components/shell-shared-facade.js";
+export interface SystemClipboardImageReader {
+    hasImage(): boolean;
+    getImageBinary?(): Promise<readonly number[]>;
+    getImageBase64?(): Promise<string>;
+}
+/** Load the native adapter during shell startup so the first paste is warm. */
+export declare function preloadSystemClipboard(): void;
+/**
+ * Reads plain text through platform clipboard commands without importing Pi's
+ * private clipboard module. Failures are deliberately non-fatal: a denied or
+ * unavailable clipboard simply makes the paste action a no-op.
+ */
+export declare function readSystemClipboardContent(signal?: AbortSignal, strict?: boolean): Promise<PiShellClipboardContent | null>;
+export declare function readSystemClipboardImage(reader: SystemClipboardImageReader): Promise<{
+    readonly data: string;
+    readonly mimeType: string;
+} | null>;
+export declare function readSystemClipboardText(signal?: AbortSignal, strict?: boolean): Promise<string | null>;
+export declare function writeSystemClipboardText(text: string): Promise<void>;

package/dist/app/session-shell/system-clipboard.js

@@ -0,0 +1,159 @@
+import { execFile } from "node:child_process";
+import { canonicalizeClipboardImage } from "./clipboard-image.js";
+import { ImageAttachmentError } from "../../contracts/owned-ui/index.js";
+import { assertSourceBytes } from "./image-source.js";
+const MAX_CLIPBOARD_BYTES = 16 * 1024 * 1024;
+let nativeClipboardPromise;
+let pendingClipboardWrite = Promise.resolve();
+/** Load the native adapter during shell startup so the first paste is warm. */
+export function preloadSystemClipboard() {
+    if (process.platform === "win32" || process.platform === "darwin")
+        void nativeClipboard();
+}
+/**
+ * Reads plain text through platform clipboard commands without importing Pi's
+ * private clipboard module. Failures are deliberately non-fatal: a denied or
+ * unavailable clipboard simply makes the paste action a no-op.
+ */
+export async function readSystemClipboardContent(signal, strict = false) {
+    await pendingClipboardWrite;
+    const native = await nativeClipboard();
+    if (native !== null) {
+        try {
+            if (process.platform === "win32" && native.availableFormats().some(isFileDropFormat)) {
+                const files = await readSystemClipboardText(signal, strict);
+                if (files !== null)
+                    return { kind: "text", text: files };
+            }
+            const image = await readSystemClipboardImage(native);
+            if (image !== null)
+                return { kind: "image", ...image };
+        }
+        catch (error) {
+            if (error instanceof ImageAttachmentError)
+                throw error;
+            // Compatibility: fall through to text and platform readers.
+        }
+    }
+    const text = await readSystemClipboardText(signal, strict);
+    return text === null ? null : { kind: "text", text };
+}
+export async function readSystemClipboardImage(reader) {
+    if (!reader.hasImage())
+        return null;
+    if (reader.getImageBinary !== undefined) {
+        try {
+            const bytes = await reader.getImageBinary();
+            if (bytes.length > 0)
+                assertSourceBytes(bytes.length);
+            if (bytes.length > 0 && bytes.every(byte => Number.isInteger(byte) && byte >= 0 && byte <= 255)) {
+                return canonicalizeClipboardImage({
+                    data: Buffer.from(bytes).toString("base64"),
+                    mimeType: "image/png",
+                }, true);
+            }
+        }
+        catch (error) {
+            if (error instanceof ImageAttachmentError)
+                throw error;
+            // Compatibility: older or partially available native bindings may still expose base64.
+        }
+    }
+    if (reader.getImageBase64 !== undefined) {
+        try {
+            return canonicalizeClipboardImage({
+                data: await reader.getImageBase64(),
+                mimeType: "image/png",
+            }, true);
+        }
+        catch (error) {
+            if (error instanceof ImageAttachmentError)
+                throw error;
+            // Compatibility: fall through to the caller's text path.
+        }
+    }
+    return null;
+}
+export async function readSystemClipboardText(signal, strict = false) {
+    // Concurrency: Ctrl+C/Ctrl+X and Ctrl+V can arrive in adjacent input turns. Serialize the
+    // read behind our native write so paste never observes the previous value.
+    await pendingClipboardWrite;
+    if (process.platform === "win32" || process.platform === "darwin") {
+        const native = await nativeClipboard();
+        if (native !== null) {
+            try {
+                const text = await native.getText();
+                if (text.length > 0)
+                    return text;
+                // Compatibility: a cold native adapter can report empty before the platform
+                // command can observe the existing clipboard. Treat empty as inconclusive
+                // and continue within this request's existing abort/deadline boundary.
+            }
+            catch {
+                // Compatibility: fall through to the platform command.
+            }
+        }
+    }
+    if (process.platform === "win32") {
+        const script = [
+            "[Console]::OutputEncoding=[System.Text.Encoding]::UTF8",
+            "$t=Get-Clipboard -Raw -ErrorAction SilentlyContinue",
+            "if ($null -ne $t -and $t.Length -gt 0) {[Console]::Out.Write($t)} else {$f=Get-Clipboard -Format FileDropList -ErrorAction SilentlyContinue; if ($f) {[Console]::Out.Write(($f | ForEach-Object {$_.FullName}) -join [Environment]::NewLine)}}",
+        ].join("; ");
+        return execClipboard("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], signal, strict);
+    }
+    if (process.platform === "darwin")
+        return execClipboard("pbpaste", [], signal, strict);
+    try {
+        const value = await execClipboard("wl-paste", ["--no-newline", "--type", "text"], signal, strict);
+        // Compatibility: an empty Wayland result does not prove that the X11
+        // clipboard is empty on mixed sessions. Let the existing fallback decide.
+        if (value !== null)
+            return value;
+    }
+    catch { /* Compatibility: X11 may be available when the Wayland command is not. */ }
+    return execClipboard("xclip", ["-selection", "clipboard", "-o"], signal, strict);
+}
+export function writeSystemClipboardText(text) {
+    const write = async () => {
+        const native = await nativeClipboard();
+        if (native !== null) {
+            try {
+                await native.setText(text);
+                return;
+            }
+            catch {
+                // Compatibility: the caller still emits its terminal clipboard fallback.
+            }
+        }
+    };
+    const operation = pendingClipboardWrite.then(write, write);
+    pendingClipboardWrite = operation.catch(() => { });
+    return operation;
+}
+function nativeClipboard() {
+    nativeClipboardPromise ??= import("@mariozechner/clipboard").catch(() => null);
+    return nativeClipboardPromise;
+}
+function isFileDropFormat(format) {
+    return /(?:filedrop|hdrop|shell idlist)/iu.test(format);
+}
+function execClipboard(command, args, signal, strict = false) {
+    if (signal?.aborted)
+        return strict ? Promise.reject(new ImageAttachmentError("paste-timeout")) : Promise.resolve(null);
+    return new Promise((resolve, reject) => {
+        execFile(command, args, {
+            encoding: "utf8",
+            maxBuffer: MAX_CLIPBOARD_BYTES,
+            timeout: 5_000,
+            windowsHide: true,
+            ...(strict ? { killSignal: "SIGKILL" } : {}),
+            ...(signal === undefined ? {} : { signal }),
+        }, (error, stdout) => {
+            if (error && strict)
+                reject(new ImageAttachmentError("paste-unavailable"));
+            else
+                resolve(error || stdout.length === 0 ? null : stdout);
+        });
+    });
+}

package/dist/app/session-shell/text-paste.d.ts

@@ -0,0 +1,5 @@
+/** Normalize clipboard text and classify its compact label using the pinned Pi 0.84.2 paste policy. */
+export declare function prepareTextPaste(source: string): {
+    readonly text: string;
+    readonly label?: string;
+};

package/dist/app/session-shell/text-paste.js

@@ -0,0 +1,16 @@
+/** Normalize clipboard text and classify its compact label using the pinned Pi 0.84.2 paste policy. */
+export function prepareTextPaste(source) {
+    // Compatibility: extended-key terminals can encode literal controls inside bracketed paste.
+    const decoded = source.replace(/\x1b\[(\d+);5u/g, (sequence, value) => {
+        const code = Number(value);
+        if (code >= 65 && code <= 90)
+            return String.fromCharCode(code - 64);
+        if (code >= 97 && code <= 122)
+            return String.fromCharCode(code - 96);
+        return sequence;
+    });
+    const text = decoded.replace(/\r\n?/g, "\n").replace(/\t/g, "    ").replace(/[\x00-\x09\x0b-\x1f]/g, "");
+    const lines = text.split("\n").length;
+    const label = lines > 10 ? `+${lines} lines` : text.length > 1000 ? `${text.length} chars` : undefined;
+    return { text, ...(label === undefined ? {} : { label }) };
+}

package/dist/cli/capabilities.d.ts

@@ -0,0 +1,6 @@
+/** The Pi comparison launch is a prerelease development instrument, not product. */
+export interface CliCapabilities {
+    readonly developmentComparison: boolean;
+}
+export declare function cliCapabilities(version: string): CliCapabilities;
+export declare function isPrereleaseVersion(version: string): boolean;

package/dist/cli/capabilities.js

@@ -0,0 +1,7 @@
+import { prerelease } from "semver";
+export function cliCapabilities(version) {
+    return Object.freeze({ developmentComparison: isPrereleaseVersion(version) });
+}
+export function isPrereleaseVersion(version) {
+    return (prerelease(version)?.length ?? 0) > 0;
+}

package/dist/cli/dispatch.d.ts

@@ -0,0 +1,53 @@
+import { type InteractiveLaunchIntent, type LaunchProfileId, type SessionSelection } from "../features/launch/index.js";
+import type { CliCapabilities } from "./capabilities.js";
+import type { PackageCommandRequest } from "./packages.js";
+import type { SessionContextRequest } from "./session-context.js";
+import { type PackageCliVerb, type PackageCommandNamespace, type PackageSyntaxDiagnostic } from "./package-messages.js";
+export type UpdateChannel = "stable" | "next";
+export interface CliHandlers {
+    readonly launch: (intent: InteractiveLaunchIntent) => Promise<number>;
+    readonly version: () => Promise<number>;
+    readonly update: (channel: UpdateChannel, target?: string) => Promise<number>;
+    readonly packages: (request: PackageCommandRequest) => Promise<number>;
+    readonly sessionContext: (request: SessionContextRequest) => Promise<number>;
+}
+export interface CliOutput {
+    readonly stdout: (message: string) => void;
+    readonly stderr: (message: string) => void;
+}
+export declare function cliUsage(capabilities: CliCapabilities): string;
+export declare function cliHelp(capabilities: CliCapabilities): string;
+export declare function dispatchCli(arguments_: readonly string[], handlers: CliHandlers, output: CliOutput, capabilities: CliCapabilities): Promise<number>;
+export type CliCommand = {
+    readonly kind: "noop";
+} | {
+    readonly kind: "help";
+} | {
+    readonly kind: "package-help";
+    readonly verb: PackageCliVerb;
+    readonly namespace: PackageCommandNamespace;
+} | {
+    readonly kind: "package-error";
+    readonly diagnostic: PackageSyntaxDiagnostic;
+    readonly namespace: PackageCommandNamespace;
+} | {
+    readonly kind: "launch";
+    readonly profileId: LaunchProfileId;
+    readonly sessionSelection?: SessionSelection;
+} | {
+    readonly kind: "version";
+} | {
+    readonly kind: "update";
+    readonly channel: UpdateChannel;
+    readonly target?: string;
+} | {
+    readonly kind: "packages";
+    readonly request: PackageCommandRequest;
+} | {
+    readonly kind: "session-context";
+    readonly request: SessionContextRequest;
+} | {
+    readonly kind: "error";
+    readonly message: string;
+};
+export declare function parseCliCommand(arguments_: readonly string[], capabilities: CliCapabilities): CliCommand;

package/dist/cli/dispatch.js

@@ -0,0 +1,287 @@
+import { interactiveLaunchIntent, parseSessionSelection } from "../features/launch/index.js";
+import { packageCommandHelp, renderPackageSyntax, } from "./package-messages.js";
+import { PRODUCT_TEXT } from "../product-identity.js";
+export function cliUsage(capabilities) {
+    return PRODUCT_TEXT.usage([
+        "",
+        "--session <path|id>",
+        "--session-dir <dir> --session <path|id>",
+        ...(capabilities.developmentComparison ? ["pi"] : []),
+        "help",
+        "version",
+        "update",
+        "update --develop [preview-or-version]",
+        "update --models",
+        "update --extensions",
+        "update <source>",
+        "install <source>",
+        "remove <source>",
+        "uninstall <source>",
+        "list",
+        "session link-worktree <path>",
+        "session unlink-worktree",
+    ]);
+}
+export function cliHelp(capabilities) {
+    const command = PRODUCT_TEXT.commandName;
+    return [
+        "Common:",
+        `  ${command}`,
+        `  ${command} --session <path|id>`,
+        `  ${command} --session-dir <dir> --session <path|id>`,
+        ...(capabilities.developmentComparison ? [`  ${command} pi`] : []),
+        `  ${command} help`,
+        `  ${command} version`,
+        "",
+        "Update:",
+        `  ${command} update`,
+        `  ${command} update --develop [preview-or-version]`,
+        `  ${command} update --models`,
+        `  ${command} update --extensions`,
+        `  ${command} update <source>`,
+        "",
+        "Packages:",
+        `  ${command} install <source>`,
+        `  ${command} remove <source>`,
+        `  ${command} uninstall <source>`,
+        `  ${command} list`,
+        "",
+        "Session context:",
+        `  ${command} session link-worktree <path>`,
+        `  ${command} session unlink-worktree`,
+        "",
+    ].join("\n");
+}
+const PROFILE_WORDS = new Set(["pi"]);
+export async function dispatchCli(arguments_, handlers, output, capabilities) {
+    const command = parseCliCommand(arguments_, capabilities);
+    if (command.kind === "noop")
+        return 0;
+    if (command.kind === "help") {
+        output.stdout(cliHelp(capabilities));
+        return 0;
+    }
+    if (command.kind === "package-help") {
+        output.stdout(packageCommandHelp(command.verb, command.namespace));
+        return 0;
+    }
+    if (command.kind === "package-error") {
+        output.stderr(renderPackageSyntax(command.diagnostic, command.namespace));
+        return 2;
+    }
+    if (command.kind === "error") {
+        output.stderr(`${command.message}\n`);
+        return 2;
+    }
+    if (command.kind === "launch")
+        return await handlers.launch(interactiveLaunchIntent(command.profileId, command.sessionSelection));
+    if (command.kind === "version")
+        return await handlers.version();
+    if (command.kind === "packages")
+        return await handlers.packages(command.request);
+    if (command.kind === "session-context")
+        return await handlers.sessionContext(command.request);
+    return await handlers.update(command.channel, command.target);
+}
+export function parseCliCommand(arguments_, capabilities) {
+    if (arguments_.length === 0)
+        return { kind: "launch", profileId: "a1" };
+    const [command, ...rest] = arguments_;
+    if (command === "--session" || command === "--session-dir") {
+        try {
+            const sessionSelection = parseSessionSelection(arguments_);
+            return { kind: "launch", profileId: "a1", ...(sessionSelection === undefined ? {} : { sessionSelection }) };
+        }
+        catch (error) {
+            return { kind: "error", message: PRODUCT_TEXT.diagnostic(`could not parse session launch: ${error instanceof Error ? error.message : String(error)}`) };
+        }
+    }
+    if (command === "help" || command === "--help" || command === "-h")
+        return withoutArguments(rest, { kind: "help" });
+    if (command === "version" || command === "--version" || command === "-v")
+        return withoutArguments(rest, { kind: "version" });
+    if (command === "install" || command === "remove" || command === "uninstall" || command === "list") {
+        return parsePackageCommand(arguments_, "direct");
+    }
+    if (command === "pi") {
+        if (rest.length > 0)
+            return parsePackageCommand(rest, "pi");
+        return capabilities.developmentComparison ? { kind: "launch", profileId: "pi" } : { kind: "noop" };
+    }
+    if (command === "update")
+        return parseUpdate(rest);
+    if (command === "session")
+        return parseSessionContext(rest);
+    if (command?.startsWith("update:"))
+        return { kind: "noop" };
+    // Rationale: unsupported and reserved command spaces are deliberately quiet. Help is
+    // explicit, and a typo must never start an interactive or maintenance path.
+    return { kind: "noop" };
+}
+function parseSessionContext(rest) {
+    const [action, value, extra] = rest;
+    if (action === "link-worktree") {
+        if (value === undefined)
+            return { kind: "error", message: PRODUCT_TEXT.diagnostic("session link-worktree requires one path.") };
+        if (extra !== undefined)
+            return { kind: "error", message: PRODUCT_TEXT.diagnostic("session link-worktree accepts one path.") };
+        return { kind: "session-context", request: { action, path: value } };
+    }
+    if (action === "unlink-worktree") {
+        if (value !== undefined)
+            return { kind: "error", message: PRODUCT_TEXT.diagnostic("session unlink-worktree does not accept arguments.") };
+        return { kind: "session-context", request: { action } };
+    }
+    return { kind: "error", message: PRODUCT_TEXT.diagnostic("session accepts link-worktree <path> or unlink-worktree.") };
+}
+/**
+ * Stable update is the empty form. `--develop` selects the moving development
+ * head or one immutable numbered preview, while model refresh remains a separate
+ * operation that cannot be combined with either update channel.
+ */
+function parseUpdate(rest) {
+    if (rest.some(value => value === "--help" || value === "-h")) {
+        return { kind: "package-help", verb: "update", namespace: "direct" };
+    }
+    if (rest.length === 0)
+        return { kind: "update", channel: "stable" };
+    const [selector, ...values] = rest;
+    // Compatibility: removed notation is unsupported rather than deprecated.
+    if (selector === "self")
+        return { kind: "noop" };
+    if (selector === "--develop") {
+        if (values.length === 0)
+            return { kind: "update", channel: "next" };
+        if (values.length > 1)
+            return updateGrammarError("--develop accepts at most one preview number or version.");
+        const [target] = values;
+        if (target === undefined || !isDevelopmentTarget(target)) {
+            return updateGrammarError(`--develop received an unusable preview: ${target ?? ""}`);
+        }
+        return { kind: "update", channel: "next", target };
+    }
+    if (selector === "--models") {
+        if (values.length > 0)
+            return updateGrammarError("--models cannot be combined with another update selector.");
+        return { kind: "packages", request: { verb: "refresh-models", source: null } };
+    }
+    if (selector === "pi")
+        return pinnedPiUpdateError();
+    if (selector === "--self" || selector === "--all")
+        return unknownOption(selector, "update");
+    return parsePackageUpdate(rest, "direct");
+}
+function isDevelopmentTarget(target) {
+    return /^[1-9]\d*$/.test(target) || /^\d+\.\d+\.\d+-dev\.[1-9]\d*$/.test(target);
+}
+function updateGrammarError(detail) {
+    return { kind: "error", message: PRODUCT_TEXT.diagnostic(`could not parse update: ${detail}`) };
+}
+function parsePackageCommand(arguments_, namespace) {
+    const [verb, ...rest] = arguments_;
+    if ((verb === "install" || verb === "remove" || verb === "uninstall" || verb === "list" || verb === "update")
+        && rest.some(value => value === "--help" || value === "-h")) {
+        return { kind: "package-help", verb: verb === "uninstall" ? "remove" : verb, namespace };
+    }
+    if (verb === "install" || verb === "remove" || verb === "uninstall") {
+        return parseSourceCommand(verb === "install" ? "install" : "remove", rest, namespace);
+    }
+    if (verb === "list") {
+        const flag = rest.find(argument => argument.startsWith("-"));
+        if (flag !== undefined)
+            return packageOptionError(flag, "list", namespace);
+        if (rest[0] !== undefined)
+            return packageSyntax({ verb: "list", kind: "unexpected-argument", value: rest[0] }, namespace);
+        return { kind: "packages", request: { verb: "list", source: null } };
+    }
+    if (verb === "update")
+        return parsePackageUpdate(rest, namespace);
+    return { kind: "noop" };
+}
+function parsePackageUpdate(rest, namespace) {
+    if (rest.length === 0)
+        return pinnedPiUpdateError();
+    if (rest.length > 1) {
+        const unknown = rest.find(value => value.startsWith("-") && !["--extensions", "--models", "--self", "--all"].includes(value));
+        if (unknown !== undefined)
+            return packageOptionError(unknown, "update", namespace);
+        if (rest.includes("--self") || rest.includes("--all") || rest.includes("self") || rest.includes("pi"))
+            return pinnedPiUpdateError();
+        if (rest.every(value => value === rest[0]) && rest[0]?.startsWith("-")) {
+            const command = namespace === "direct" ? "update" : "pi update";
+            return { kind: "error", message: PRODUCT_TEXT.diagnostic(`${command} accepts one target.`) };
+        }
+        const sources = rest.filter(value => !value.startsWith("-"));
+        if (sources[1] !== undefined)
+            return packageSyntax({ verb: "update", kind: "unexpected-argument", value: sources[1] }, namespace);
+        const message = rest.includes("--models")
+            ? rest.includes("--extensions")
+                ? "--models cannot be combined with --self, --extensions, --all, or --extension"
+                : "--models cannot be combined with a positional source"
+            : "positional update targets cannot be combined with --self, --extensions, or --all";
+        return packageSyntax({ verb: "update", kind: "conflict", message }, namespace);
+    }
+    const [target] = rest;
+    if (target === "--extensions")
+        return { kind: "packages", request: { verb: "update", source: null } };
+    if (target === "--models")
+        return { kind: "packages", request: { verb: "refresh-models", source: null } };
+    if (target === "--self" || target === "--all" || target === "self" || target === "pi")
+        return pinnedPiUpdateError();
+    if (target === undefined || target.startsWith("-"))
+        return packageOptionError(target ?? "", "update", namespace);
+    return { kind: "packages", request: { verb: "update", source: target } };
+}
+function pinnedPiUpdateError() {
+    return {
+        kind: "error",
+        message: [
+            PRODUCT_TEXT.diagnostic("pins its certified Pi runtime and cannot update it independently."),
+            "Use:",
+            `  ${PRODUCT_TEXT.commandName} update                    Update a1`,
+            `  ${PRODUCT_TEXT.commandName} update --extensions       Update Pi-compatible packages`,
+            `  ${PRODUCT_TEXT.commandName} update --models           Refresh model catalogs`,
+        ].join("\n"),
+    };
+}
+function parseSourceCommand(verb, rest, namespace) {
+    const flag = rest.find(argument => argument.startsWith("-"));
+    if (flag !== undefined)
+        return packageOptionError(flag, verb, namespace);
+    const [source, extra] = rest;
+    if (extra !== undefined)
+        return packageSyntax({ verb, kind: "unexpected-argument", value: extra }, namespace);
+    if (source === undefined)
+        return packageSyntax({ verb, kind: "missing-source" }, namespace);
+    if (PROFILE_WORDS.has(source))
+        return profileRejection(verb);
+    return { kind: "packages", request: { verb, source } };
+}
+function packageSyntax(diagnostic, namespace) {
+    return { kind: "package-error", diagnostic, namespace };
+}
+function packageOptionError(option, verb, namespace) {
+    if (option.startsWith("--profile") || option === "-l" || option === "--local")
+        return profileRejection(verb);
+    // Compatibility: these recognized Pi flags remain outside A1's supported subset.
+    if (["--extension", "--approve", "--no-approve", "-a", "-na", "--force"].includes(option)) {
+        return unknownOption(option, namespace === "direct" ? verb : `pi ${verb}`);
+    }
+    return packageSyntax({ verb, kind: "unknown-option", value: option }, namespace);
+}
+function withoutArguments(rest, command) {
+    if (rest.length === 0)
+        return command;
+    return { kind: "error", message: PRODUCT_TEXT.diagnostic("commands do not accept additional arguments.") };
+}
+function profileRejection(verb) {
+    return {
+        kind: "error",
+        message: PRODUCT_TEXT.diagnostic(`manages packages in its own profile, so ${verb} takes no profile; Pi manages Pi's own profile.`),
+    };
+}
+function unknownOption(option, verb) {
+    if (option.startsWith("--profile"))
+        return profileRejection(verb);
+    return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unknown option for ${verb}: ${option}`) };
+}