@oxygen-agent/cli 1.46.0 → 1.64.5

package/dist/local-custom-http-column.js

@@ -387,7 +387,7 @@ async function readLocalHttpResponseBody(response) {
     if (!text)
         return null;
     const contentType = response.headers.get("content-type") ?? "";
-    const looksJson = contentType.toLowerCase().includes("json") || /^[\s\n\r]*[\[{]/.test(text);
+    const looksJson = contentType.toLowerCase().includes("json") || /^[\s\n\r]*[\[{]/.test(text); // skipcq: JS-0097
     if (!looksJson)
         return text;
     try {

package/dist/skills.d.ts

@@ -0,0 +1,41 @@
+import { execFileSync } from "node:child_process";
+export type ExecFileSyncLike = typeof execFileSync;
+export type SkillsInstallOptions = {
+    json?: boolean;
+    apiUrl?: string;
+    agents?: string | string[];
+    skill?: string;
+    project?: boolean;
+    copy?: boolean;
+};
+export type SkillsListOptions = {
+    json?: boolean;
+    apiUrl?: string;
+};
+export type SkillsDoctorOptions = {
+    json?: boolean;
+    apiUrl?: string;
+};
+export type AutomaticSkillsInstallResult = {
+    attempted: boolean;
+    ok: boolean;
+    command: string;
+    reason?: string;
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+};
+export declare function listAgentSkills(options: SkillsListOptions): Promise<Record<string, unknown>>;
+export declare function doctorAgentSkills(options: SkillsDoctorOptions): Promise<Record<string, unknown>>;
+export declare function installAgentSkills(options: SkillsInstallOptions, runtime?: {
+    env?: NodeJS.ProcessEnv;
+    execFileSync?: ExecFileSyncLike;
+}): Record<string, unknown>;
+export declare function runAutomaticSkillsInstall(options?: {
+    apiUrl?: string;
+    env?: NodeJS.ProcessEnv;
+    execFileSync?: ExecFileSyncLike;
+}): AutomaticSkillsInstallResult;
+export declare function skippedAutomaticSkillsInstall(reason: string, apiUrl?: string): AutomaticSkillsInstallResult;

package/dist/skills.js

@@ -0,0 +1,325 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { OxygenError, toFailure } from "@oxygen/shared";
+import { defaultApiUrl, normalizeApiUrl } from "./credentials.js";
+const DEFAULT_SKILL_AGENTS = ["codex", "claude-code", "cursor"];
+const SKILL_INDEX_PATH = "/.well-known/skills/index.json";
+export async function listAgentSkills(options) {
+    const apiUrl = normalizeApiUrl(readOption(options.apiUrl) ?? defaultApiUrl());
+    const indexUrl = skillIndexUrl(apiUrl);
+    const index = await inspectSkillIndex(indexUrl);
+    const installed = detectInstalledAgentSkills();
+    return {
+        index_url: indexUrl,
+        available: {
+            detected: index.reachable,
+            names: index.skill_names,
+            skills: index.skills,
+            ...(index.error ? { error: index.error } : {}),
+        },
+        installed,
+        recommended_install_command: recommendedSkillsInstallCommand(apiUrl),
+        install_command_args: recommendedSkillsInstallArgs(apiUrl),
+    };
+}
+export async function doctorAgentSkills(options) {
+    const apiUrl = normalizeApiUrl(readOption(options.apiUrl) ?? defaultApiUrl());
+    const indexUrl = skillIndexUrl(apiUrl);
+    const index = await inspectSkillIndex(indexUrl);
+    const installer = inspectSkillsInstaller();
+    const installed = detectInstalledAgentSkills();
+    const data = {
+        index_url: indexUrl,
+        index,
+        installer,
+        installed,
+        recommended_install_command: recommendedSkillsInstallCommand(apiUrl),
+        install_command_args: recommendedSkillsInstallArgs(apiUrl),
+    };
+    if (!index.reachable) {
+        throw new OxygenError("skills_index_unreachable", "Oxygen skill index is not reachable.", {
+            details: data,
+            exitCode: 1,
+        });
+    }
+    if (!installer.available) {
+        throw new OxygenError("skills_installer_unavailable", "The local npx installer command is not available.", {
+            details: data,
+            exitCode: 1,
+        });
+    }
+    return data;
+}
+export function installAgentSkills(options, runtime = {}) {
+    const apiUrl = normalizeApiUrl(readOption(options.apiUrl) ?? defaultApiUrl());
+    const indexUrl = skillIndexUrl(apiUrl);
+    const agents = readWords(options.agents ?? DEFAULT_SKILL_AGENTS);
+    const skill = readOption(options.skill) ?? "*";
+    const args = installerAddArgs(indexUrl, agents, skill);
+    if (!options.project)
+        args.push("--global");
+    if (options.copy)
+        args.push("--copy");
+    let output = "";
+    try {
+        const exec = runtime.execFileSync ?? execFileSync;
+        output = String(exec("npx", args, {
+            encoding: "utf8",
+            env: runtime.env ?? process.env,
+            stdio: ["ignore", "pipe", "pipe"],
+        }));
+    }
+    catch (error) {
+        const failure = error;
+        throw new OxygenError("skills_install_failed", "Unable to install Oxygen agent skills.", {
+            details: {
+                index_url: indexUrl,
+                stdout: failure.stdout?.slice(0, 2000) ?? "",
+                stderr: failure.stderr?.slice(0, 2000) ?? failure.message ?? "unknown",
+            },
+            exitCode: 1,
+        });
+    }
+    return {
+        indexUrl,
+        index_url: indexUrl,
+        agents,
+        skill,
+        scope: options.project ? "project" : "global",
+        output,
+    };
+}
+export function runAutomaticSkillsInstall(options = {}) {
+    const apiUrl = normalizeApiUrl(readOption(options.apiUrl) ?? defaultApiUrl());
+    const env = options.env ?? process.env;
+    if (env.OXYGEN_SKIP_SKILLS === "1") {
+        return skippedAutomaticSkillsInstall("OXYGEN_SKIP_SKILLS=1", apiUrl);
+    }
+    const command = recommendedSkillsInstallCommand(apiUrl);
+    try {
+        installAgentSkills({
+            apiUrl,
+            agents: DEFAULT_SKILL_AGENTS,
+            skill: "*",
+            json: true,
+        }, {
+            env,
+            ...(options.execFileSync ? { execFileSync: options.execFileSync } : {}),
+        });
+        return {
+            attempted: true,
+            ok: true,
+            command,
+        };
+    }
+    catch (error) {
+        const failure = toFailure("skills install", error);
+        return {
+            attempted: true,
+            ok: false,
+            command,
+            error: failure.error,
+        };
+    }
+}
+export function skippedAutomaticSkillsInstall(reason, apiUrl = normalizeApiUrl(defaultApiUrl())) {
+    return {
+        attempted: false,
+        ok: true,
+        command: recommendedSkillsInstallCommand(apiUrl),
+        reason,
+    };
+}
+async function inspectSkillIndex(indexUrl) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 10_000);
+    timeout.unref?.();
+    try {
+        const response = await fetch(indexUrl, {
+            headers: { Accept: "application/json" },
+            signal: controller.signal,
+        });
+        const text = await response.text();
+        if (!response.ok) {
+            return emptySkillIndexInspection({
+                status: response.status,
+                error: { code: "http_error", message: `HTTP ${response.status}` },
+            });
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (error) {
+            return emptySkillIndexInspection({
+                status: response.status,
+                error: {
+                    code: "invalid_json",
+                    message: error instanceof Error ? error.message : "Invalid JSON.",
+                },
+            });
+        }
+        let index;
+        try {
+            index = parseSkillIndex(parsed);
+        }
+        catch (error) {
+            return emptySkillIndexInspection({
+                status: response.status,
+                error: {
+                    code: error instanceof OxygenError ? error.code : "invalid_skill_index",
+                    message: error instanceof Error ? error.message : "Skill index shape is invalid.",
+                },
+            });
+        }
+        return {
+            reachable: true,
+            status: response.status,
+            version: index.version,
+            base_url: index.base_url,
+            skill_names: index.skills.map((skill) => skill.name),
+            skills: index.skills,
+        };
+    }
+    catch (error) {
+        const aborted = error instanceof Error && error.name === "AbortError";
+        return emptySkillIndexInspection({
+            status: null,
+            error: {
+                code: aborted ? "network_timeout" : "network_error",
+                message: error instanceof Error ? error.message : "Unable to reach skill index.",
+            },
+        });
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function emptySkillIndexInspection(input) {
+    return {
+        reachable: false,
+        status: input.status,
+        version: null,
+        base_url: null,
+        skill_names: [],
+        skills: [],
+        error: input.error,
+    };
+}
+function parseSkillIndex(value) {
+    if (!isRecord(value) || !Array.isArray(value.skills)) {
+        throw new OxygenError("invalid_skill_index", "Skill index must include a skills array.", {
+            exitCode: 1,
+        });
+    }
+    const skills = value.skills
+        .map((entry) => {
+        if (!isRecord(entry) || typeof entry.name !== "string" || !entry.name.trim())
+            return null;
+        return {
+            name: entry.name.trim(),
+            title: typeof entry.title === "string" ? entry.title : null,
+            description: typeof entry.description === "string" ? entry.description : null,
+            entrypoint: typeof entry.entrypoint === "string" ? entry.entrypoint : null,
+        };
+    })
+        .filter((entry) => entry !== null);
+    return {
+        version: typeof value.version === "string" ? value.version : null,
+        base_url: typeof value.base_url === "string" ? value.base_url : null,
+        skills,
+    };
+}
+function inspectSkillsInstaller() {
+    const result = spawnSync("npx", ["--version"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 5000,
+    });
+    const error = result.error instanceof Error ? result.error.message : null;
+    const stdout = typeof result.stdout === "string" ? result.stdout.trim() : "";
+    const stderr = typeof result.stderr === "string" ? result.stderr.trim() : "";
+    return {
+        command_path: "npx",
+        check_args: ["--version"],
+        available: result.status === 0 && !error,
+        version: stdout || null,
+        ...(error ? { error } : {}),
+        ...(stderr ? { stderr: stderr.slice(0, 1000) } : {}),
+    };
+}
+function detectInstalledAgentSkills() {
+    const roots = [
+        { agent: "codex", path: join(process.env.CODEX_HOME ?? join(homedir(), ".codex"), "skills") },
+        { agent: "claude-code", path: join(process.env.CLAUDE_HOME ?? join(homedir(), ".claude"), "skills") },
+        { agent: "cursor", path: join(process.env.CURSOR_HOME ?? join(homedir(), ".cursor"), "skills") },
+        { agent: "project", path: resolve(".agents", "skills") },
+    ];
+    const names = new Set();
+    const locations = [];
+    for (const root of roots) {
+        if (!existsSync(root.path))
+            continue;
+        try {
+            const rootNames = readdirSync(root.path, { withFileTypes: true })
+                .filter((entry) => entry.isDirectory() && entry.name.startsWith("oxygen-"))
+                .map((entry) => entry.name)
+                .sort();
+            for (const name of rootNames)
+                names.add(name);
+            locations.push({ ...root, names: rootNames });
+        }
+        catch {
+            locations.push({ ...root, names: [] });
+        }
+    }
+    return {
+        detected: locations.length > 0,
+        names: [...names].sort(),
+        locations,
+    };
+}
+function skillIndexUrl(apiUrl) {
+    return `${apiUrl}${SKILL_INDEX_PATH}`;
+}
+function recommendedSkillsInstallCommand(apiUrl) {
+    return recommendedSkillsInstallArgs(apiUrl)
+        .map((entry) => entry === "*" ? "'*'" : entry)
+        .join(" ");
+}
+function recommendedSkillsInstallArgs(apiUrl) {
+    const args = ["oxygen", "skills", "install"];
+    if (apiUrl !== normalizeApiUrl(defaultApiUrl())) {
+        args.push("--api-url", apiUrl);
+    }
+    args.push("--agents", ...DEFAULT_SKILL_AGENTS, "--skill", "*", "--json");
+    return args;
+}
+function installerAddArgs(indexUrl, agents, skill) {
+    return [
+        "skills",
+        "add",
+        indexUrl,
+        "--agents",
+        ...agents,
+        "--yes",
+        "--skill",
+        skill,
+        "--full-depth",
+    ];
+}
+function readWords(value) {
+    const text = Array.isArray(value) ? value.join(" ") : value;
+    return text
+        .split(/[,\s]+/)
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}
+function readOption(value) {
+    return value?.trim() ? value.trim() : null;
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/dist/update.d.ts

@@ -0,0 +1,34 @@
+import { spawnSync } from "node:child_process";
+import { type AutomaticSkillsInstallResult, type ExecFileSyncLike } from "./skills.js";
+type SpawnResult = ReturnType<typeof spawnSync>;
+type SpawnSyncLike = (command: string, args: string[], options: {
+    encoding: BufferEncoding;
+    env: NodeJS.ProcessEnv;
+    stdio: "inherit" | ["ignore", "pipe", "pipe"];
+    windowsHide: boolean;
+    windowsVerbatimArguments?: boolean;
+}) => SpawnResult;
+export type UpdateOptions = {
+    json?: boolean;
+    package?: string;
+    dryRun?: boolean;
+};
+export type UpdateResult = {
+    current_version: string;
+    package: string;
+    command: string;
+    dry_run: boolean;
+    updated: boolean;
+    skills_install: AutomaticSkillsInstallResult;
+};
+export declare function updateCli(options: UpdateOptions, runtime?: {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    modulePath?: string;
+    spawnSync?: SpawnSyncLike;
+    execFileSync?: ExecFileSyncLike;
+}): UpdateResult;
+export declare function detectCliInstallPrefix(modulePath?: string): string | null;
+export declare function detectCliInstallPrefixFromPath(modulePath: string): string | null;
+export declare function resolveNpmExecutables(platform?: NodeJS.Platform): string[];
+export {};

package/dist/update.js

@@ -0,0 +1,123 @@
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { OXYGEN_VERSION, OxygenError } from "@oxygen/shared";
+import { runAutomaticSkillsInstall, skippedAutomaticSkillsInstall, } from "./skills.js";
+const DEFAULT_CLI_PACKAGE_SPEC = "@oxygen-agent/cli@latest";
+// skipcq: JS-R1005 — handles platform/install-mode/dry-run combinations end-to-end
+export function updateCli(options, runtime = {}) {
+    const env = runtime.env ?? process.env;
+    const platform = runtime.platform ?? process.platform;
+    const spawn = runtime.spawnSync ?? spawnSync;
+    const packageSpec = readOption(options.package) ?? DEFAULT_CLI_PACKAGE_SPEC;
+    const prefix = detectCliInstallPrefix(runtime.modulePath);
+    const args = prefix
+        ? ["install", "-g", "--prefix", prefix, packageSpec]
+        : ["install", "-g", packageSpec];
+    // The command string is for human display (printed in dry-run / success
+    // output). Quote args that contain shell-significant characters so a
+    // copy-paste of the line works on install prefixes with spaces.
+    const command = ["npm", ...args].map(quoteForDisplay).join(" ");
+    if (options.dryRun) {
+        return {
+            current_version: OXYGEN_VERSION,
+            package: packageSpec,
+            command,
+            dry_run: true,
+            updated: false,
+            skills_install: skippedAutomaticSkillsInstall("dry_run"),
+        };
+    }
+    const attemptedExecutables = [];
+    let lastResult = null;
+    for (const invocation of resolveNpmInvocations(args, platform, env)) {
+        attemptedExecutables.push(invocation.label);
+        const result = spawn(invocation.executable, invocation.args, {
+            encoding: "utf8",
+            env,
+            stdio: options.json ? ["ignore", "pipe", "pipe"] : "inherit",
+            windowsHide: true,
+            // We pre-quote args for `cmd /d /s /c`; Node must not re-escape them
+            // or the install prefix path ends up with literal `"` characters
+            // baked in (see scripts/ci/cli-package-smoke.mjs for the same fix).
+            ...(platform === "win32" ? { windowsVerbatimArguments: true } : {}),
+        });
+        lastResult = result;
+        if (result.error && isMissingExecutableError(result.error))
+            continue;
+        if (!result.error && result.status === 0) {
+            return {
+                current_version: OXYGEN_VERSION,
+                package: packageSpec,
+                command,
+                dry_run: false,
+                updated: true,
+                skills_install: runAutomaticSkillsInstall({
+                    env,
+                    ...(runtime.execFileSync ? { execFileSync: runtime.execFileSync } : {}),
+                }),
+            };
+        }
+        break;
+    }
+    const result = lastResult;
+    throw new OxygenError("cli_update_failed", "Unable to update the Oxygen CLI.", {
+        details: {
+            command,
+            package: packageSpec,
+            exit_code: result?.status ?? null,
+            reason: result?.error instanceof Error ? result.error.message : null,
+            stderr: typeof result?.stderr === "string" && result.stderr.trim() ? result.stderr.trim().slice(0, 4000) : null,
+            attempted_executables: attemptedExecutables,
+        },
+        exitCode: 1,
+    });
+}
+export function detectCliInstallPrefix(modulePath = fileURLToPath(import.meta.url)) {
+    return detectCliInstallPrefixFromPath(modulePath);
+}
+export function detectCliInstallPrefixFromPath(modulePath) {
+    const normalizedPath = modulePath.replace(/\\/g, "/");
+    const markers = [
+        "/node_modules/@oxygen-agent/cli/dist/",
+        "/node_modules/@oxygen/cli/dist/",
+    ];
+    for (const marker of markers) {
+        const markerIndex = normalizedPath.lastIndexOf(marker);
+        if (markerIndex === -1)
+            continue;
+        const packageParent = normalizedPath.slice(0, markerIndex);
+        if (packageParent.endsWith("/lib"))
+            return packageParent.slice(0, -"/lib".length);
+        return packageParent;
+    }
+    return null;
+}
+export function resolveNpmExecutables(platform = process.platform) {
+    return platform === "win32" ? ["cmd.exe"] : ["npm"];
+}
+function readOption(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function isMissingExecutableError(error) {
+    return error.code === "ENOENT";
+}
+function resolveNpmInvocations(args, platform, env) {
+    if (platform !== "win32")
+        return [{ executable: "npm", args, label: "npm" }];
+    const shell = env.ComSpec?.trim() || "cmd.exe";
+    return [{
+            executable: shell,
+            args: ["/d", "/s", "/c", ["npm", ...args].map(quoteWindowsCmdArg).join(" ")],
+            label: shell,
+        }];
+}
+function quoteWindowsCmdArg(value) {
+    if (/^[A-Za-z0-9_@+=:,./\\-]+$/.test(value))
+        return value;
+    return `"${value.replace(/(["^&|<>()%])/g, "^$1")}"`;
+}
+function quoteForDisplay(value) {
+    if (/^[A-Za-z0-9_@+=:,./-]+$/.test(value))
+        return value;
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}

package/node_modules/@oxygen/shared/dist/billing.d.ts

@@ -108,7 +108,8 @@ export declare const ACTIVE_SUBSCRIPTION_STATUSES: readonly ["active", "trialing
 export type ActiveSubscriptionStatus = (typeof ACTIVE_SUBSCRIPTION_STATUSES)[number];
 export type ResolvedPricingPlan = PricingPlanDefinition;
 export declare function resolveBasePricingPlan(tier: string | null | undefined): ResolvedPricingPlan | null;
-export declare function applyPricingPlanMetadataOverrides(plan: PricingPlanDefinition, metadata: PricingPlanMetadata): PricingPlanDefinition;
+export declare function applyPricingPlanMetadataOverrides(// skipcq: JS-R1005
+plan: PricingPlanDefinition, metadata: PricingPlanMetadata): PricingPlanDefinition;
 export declare function isSelfServePlanTier(value: string): value is SelfServePlanTier;
 export declare function isBillingCurrency(value: string): value is BillingCurrency;
 export declare function normalizeBillingCurrency(value: string | null | undefined): BillingCurrency;

package/node_modules/@oxygen/shared/dist/billing.js

@@ -208,7 +208,8 @@ export function resolveBasePricingPlan(tier) {
     const legacy = LEGACY_PRICING_PLAN_OVERRIDES[tier];
     return legacy ?? null;
 }
-export function applyPricingPlanMetadataOverrides(plan, metadata) {
+export function applyPricingPlanMetadataOverrides(// skipcq: JS-R1005
+plan, metadata) {
     const record = readRecord(metadata);
     if (!record)
         return plan;

package/node_modules/@oxygen/shared/dist/cell-format.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared cell display formatter for CLI, MCP widgets, and the web app.
+ *
+ * One source of truth for how a stored cell value should look to a human.
+ * Storage stays untouched — this only decides what to render.
+ *
+ * Three responsibilities:
+ *  1. Format known-typed values consistently (numeric → 1,154; timestamp → ISO/short).
+ *  2. Rescue numeric-looking values that landed in a `text` column. Headcount
+ *     and similar fields routinely arrive as text from CSV imports, AI columns,
+ *     and provider adapters, so a `text` column whose values parse cleanly as
+ *     numbers still gets thousands grouping at display time.
+ *  3. Refuse to "rescue" things that aren't actually numbers (IP addresses,
+ *     version strings, phone numbers, URLs), via {@link looksLikeNumericText}.
+ */
+/** Surfaces have different escaping/length budgets, but the canonical string is shared. */
+export type CellFormatSurface = "cli" | "mcp" | "web";
+export type CellColumnLike = {
+    dataType?: string | null;
+    data_type?: string | null;
+    kind?: string | null;
+    label?: string | null;
+    key?: string | null;
+    semanticType?: string | null;
+    semantic_type?: string | null;
+};
+export type CellFormatOptions = {
+    surface: CellFormatSurface;
+    locale?: string;
+    /** When the value is rescued from a text column, callers can show a hint. */
+    onRescued?: (parsed: number) => void;
+};
+/**
+ * Canonical display string for a single cell.
+ *
+ * Returns `""` for null/undefined/empty so callers can treat the absence of
+ * a value as the absence of a string. Surface-specific concerns (HTML
+ * escaping, ellipsis budgets) belong outside this function.
+ */
+export declare function formatCellForDisplay(value: unknown, column: CellColumnLike | null | undefined, options: CellFormatOptions): string;
+/**
+ * Best-effort parse of a string that looks numeric (with or without thousands
+ * grouping, with or without dotted IP-style separators) into a finite number.
+ * Returns `null` when the string is clearly *not* a single number — IP
+ * addresses, version strings, phone numbers, anything alphabetic.
+ */
+export declare function rescueNumericText(raw: string): number | null;
+/**
+ * True when a string is unambiguously numeric (integer, decimal, grouped, or
+ * a mangled dotted form we can recover). Exported for callers that want to
+ * highlight rescue cases without re-running the formatter.
+ */
+export declare function looksLikeNumericText(value: string): boolean;
+/**
+ * Decide whether the same value-level + column-level guards used inside
+ * `formatCellForDisplay`'s text path should rescue this string. Exposed so
+ * non-formatter callers (web grid, etc.) can stay in lockstep without
+ * duplicating the heuristic.
+ */
+export declare function tryRescueTextCell(value: string, column: CellColumnLike | null | undefined): number | null;