@oxygen-agent/cli 1.50.37 → 1.98.7

package/dist/skills.d.ts

@@ -0,0 +1,47 @@
+import { execFileSync, spawnSync } from "node:child_process";
+export type ExecFileSyncLike = typeof execFileSync;
+export type SpawnSyncLike = typeof spawnSync;
+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(// skipcq: JS-R1005
+options: SkillsInstallOptions, runtime?: {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    execFileSync?: ExecFileSyncLike;
+    spawnSync?: SpawnSyncLike;
+}): Record<string, unknown>;
+export declare function runAutomaticSkillsInstall(options?: {
+    apiUrl?: string;
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    execFileSync?: ExecFileSyncLike;
+    spawnSync?: SpawnSyncLike;
+}): AutomaticSkillsInstallResult;
+export declare function skippedAutomaticSkillsInstall(reason: string, apiUrl?: string): AutomaticSkillsInstallResult;

package/dist/skills.js

@@ -0,0 +1,375 @@
+import { 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";
+import { resolveCmdShimInvocation } from "./windows-shim.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(// skipcq: JS-R1005
+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 env = runtime.env ?? process.env;
+    const platform = runtime.platform ?? process.platform;
+    const args = installerAddArgs(indexUrl, agents, skill);
+    if (!options.project)
+        args.push("--global");
+    if (options.copy)
+        args.push("--copy");
+    const invocation = resolveCmdShimInvocation("npx", args, platform, env);
+    const spawn = runtime.spawnSync ?? wrapExecFileSync(runtime.execFileSync) ?? spawnSync;
+    const result = spawn(invocation.executable, invocation.args, {
+        encoding: "utf8",
+        env,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+        ...(platform === "win32" ? { windowsVerbatimArguments: true } : {}),
+    });
+    const stdout = typeof result.stdout === "string" ? result.stdout : "";
+    const stderr = typeof result.stderr === "string" ? result.stderr : "";
+    if (result.error || (typeof result.status === "number" && result.status !== 0)) {
+        const message = result.error instanceof Error ? result.error.message : null;
+        throw new OxygenError("skills_install_failed", "Unable to install Oxygen agent skills.", {
+            details: {
+                index_url: indexUrl,
+                executable: invocation.label,
+                exit_code: typeof result.status === "number" ? result.status : null,
+                stdout: stdout.slice(0, 2000),
+                stderr: (stderr || message || "unknown").slice(0, 2000),
+            },
+            exitCode: 1,
+        });
+    }
+    return {
+        indexUrl,
+        index_url: indexUrl,
+        agents,
+        skill,
+        scope: options.project ? "project" : "global",
+        output: stdout,
+    };
+}
+// Adapt the legacy `execFileSync` runtime hook into a spawnSync-shaped return so
+// existing test fixtures (update.test.ts) keep working without a coordinated
+// rewrite. New tests should inject `spawnSync` directly.
+function wrapExecFileSync(exec) {
+    if (!exec)
+        return undefined;
+    return ((command, args, opts) => {
+        try {
+            const stdout = exec(command, args, opts);
+            return {
+                status: 0,
+                signal: null,
+                output: [],
+                pid: 0,
+                stdout: typeof stdout === "string" ? stdout : Buffer.isBuffer(stdout) ? stdout.toString("utf8") : "",
+                stderr: "",
+            };
+        }
+        catch (error) {
+            const failure = error;
+            return {
+                status: typeof failure.status === "number" ? failure.status : 1,
+                signal: null,
+                output: [],
+                pid: 0,
+                stdout: failure.stdout ?? "",
+                stderr: failure.stderr ?? failure.message ?? "",
+                error: error instanceof Error ? error : new Error(String(error)),
+            };
+        }
+    });
+}
+export function runAutomaticSkillsInstall(options = {}) {
+    const apiUrl = normalizeApiUrl(readOption(options.apiUrl) ?? defaultApiUrl());
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    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,
+            // `npx skills add` symlinks by default; on Windows that requires Developer
+            // Mode or admin elevation, so copy is the only reliable unattended path.
+            copy: platform === "win32",
+        }, {
+            env,
+            platform,
+            ...(options.execFileSync ? { execFileSync: options.execFileSync } : {}),
+            ...(options.spawnSync ? { spawnSync: options.spawnSync } : {}),
+        });
+        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 invocation = resolveCmdShimInvocation("npx", ["--version"], process.platform, process.env);
+    const result = spawnSync(invocation.executable, invocation.args, {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 5000,
+        windowsHide: true,
+        ...(process.platform === "win32" ? { windowsVerbatimArguments: true } : {}),
+    });
+    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"],
+        invocation: { executable: invocation.label, args: invocation.args },
+        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

@@ -1,4 +1,5 @@
 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;
@@ -18,12 +19,14 @@ export type UpdateResult = {
     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;

package/dist/update.js

@@ -1,7 +1,10 @@
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { OXYGEN_VERSION, OxygenError } from "@oxygen/shared";
+import { runAutomaticSkillsInstall, skippedAutomaticSkillsInstall, } from "./skills.js";
+import { quoteWindowsCmdArg } from "./windows-shim.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;
@@ -22,6 +25,7 @@ export function updateCli(options, runtime = {}) {
             command,
             dry_run: true,
             updated: false,
+            skills_install: skippedAutomaticSkillsInstall("dry_run"),
         };
     }
     const attemptedExecutables = [];
@@ -48,6 +52,11 @@ export function updateCli(options, runtime = {}) {
                 command,
                 dry_run: false,
                 updated: true,
+                skills_install: runAutomaticSkillsInstall({
+                    env,
+                    platform,
+                    ...(runtime.execFileSync ? { execFileSync: runtime.execFileSync } : {}),
+                }),
             };
         }
         break;
@@ -104,11 +113,6 @@ function resolveNpmInvocations(args, platform, env) {
             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;

package/dist/windows-shim.d.ts

@@ -0,0 +1,7 @@
+export type CmdShimInvocation = {
+    executable: string;
+    args: string[];
+    label: string;
+};
+export declare function resolveCmdShimInvocation(command: string, args: string[], platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): CmdShimInvocation;
+export declare function quoteWindowsCmdArg(value: string): string;

package/dist/windows-shim.js

@@ -0,0 +1,21 @@
+// Windows-aware command launcher. Node's `execFileSync`/`spawnSync` cannot
+// resolve `.cmd`/`.bat` shims (like `npx.cmd`) from a bare command name, so on
+// Windows we route through `cmd.exe /d /s /c <command> <args>` with
+// `windowsVerbatimArguments: true`. Spawn options must enable that flag at the
+// caller — see `update.ts` and `skills.ts` for the pattern.
+export function resolveCmdShimInvocation(command, args, platform = process.platform, env = process.env) {
+    if (platform !== "win32") {
+        return { executable: command, args, label: command };
+    }
+    const shell = env.ComSpec?.trim() || "cmd.exe";
+    return {
+        executable: shell,
+        args: ["/d", "/s", "/c", [command, ...args].map(quoteWindowsCmdArg).join(" ")],
+        label: shell,
+    };
+}
+export function quoteWindowsCmdArg(value) {
+    if (/^[A-Za-z0-9_@+=:,./\\-]+$/.test(value))
+        return value;
+    return `"${value.replace(/(["^&|<>()%])/g, "^$1")}"`;
+}

package/node_modules/@oxygen/shared/dist/cell-format.js

@@ -52,6 +52,7 @@ const IDENTIFIER_COLUMN_RE = /(?:^|[^a-z0-9])(phone|mobile|tel(?:ephone)?|fax|zi
  * a value as the absence of a string. Surface-specific concerns (HTML
  * escaping, ellipsis budgets) belong outside this function.
  */
+// skipcq: JS-R1005 — dispatches across cell types + surfaces; branches are intrinsic
 export function formatCellForDisplay(value, column, options) {
     if (value === null || value === undefined || value === "")
         return "";
@@ -198,9 +199,7 @@ function shouldRescueColumn(column) {
     const dataType = readDataType(column);
     if (dataType !== "text" && dataType !== "numeric")
         return false;
-    if (columnLooksLikeIdentifier(column))
-        return false;
-    return true;
+    return !columnLooksLikeIdentifier(column);
 }
 /**
  * Decide whether the same value-level + column-level guards used inside

package/node_modules/@oxygen/shared/dist/file-import.d.ts

@@ -10,11 +10,16 @@ export type NewTableImportRows = {
     rows: Record<string, unknown>[];
     keyBySource: Record<string, string>;
 };
+export declare const MAX_BUFFERED_IMPORT_PARSE_BYTES: number;
 export declare function inferRowsFileFormat(path: string): RowsFileFormat;
 export declare function normalizeRowsFormat(value: string | undefined, fallback: RowsFileFormat): RowsFileFormat;
 export declare function parseRowsFileBuffer(buffer: Buffer, format: RowsFileFormat, options?: {
     sheet?: string;
 }): Promise<Record<string, unknown>[]>;
+export declare function iterateRowsFileBufferBatches(buffer: Buffer, format: RowsFileFormat, options?: {
+    sheet?: string;
+    batchSize?: number;
+}): AsyncGenerator<Record<string, unknown>[]>;
 export declare function parseRowsText(text: string, format: Exclude<RowsFileFormat, "xlsx">): Record<string, unknown>[];
 export declare function inferImportColumnLabels(rows: Record<string, unknown>[]): string[];
 export declare function normalizeRowsForNewTable(rows: Record<string, unknown>[]): NewTableImportRows;