@oxygen-agent/cli 1.982.3 → 1.987.20

package/README.md

@@ -34,4 +34,4 @@ oxygen update
 
 For product documentation, visit https://oxygen-agent.com/docs. For support, visit https://oxygen-agent.com.
 
-Version: 1.982.3
+Version: 1.987.20

package/dist/functions-commands.js

@@ -3,12 +3,28 @@ import { parseJsonObject } from "./cli-values.js";
 import { requestOxygen } from "./http-client.js";
 export function registerFunctionsCommands(program, handle) {
     const functions = program.command("functions")
-        .description("Create, edit, publish and reuse Functions backed by ordinary Tables.")
-        .addHelpText("after", "\nDraft edits are isolated. Publishing updates future invocations of every caller; queued, in-flight and past runs retain their captured version. Existing caller caps never increase automatically.\nFlow: draft → describe → publish → bind → columns run --dry-run → approved run → runs.\nA bound Function executes on its own published execution table and writes named outputs back to the calling table. The call stays visible from the caller: `table-runs list --table <caller> --status all` lists the run, and the binding column's cell holds the outcome (status, outputs, credits, invocation and run ids). Address a Function by id, slug, or the display name shown by `functions list`.\nWorked example with commands: `oxygen skills install --skill oxygen-gtm --project`, then read its recipes/callable-tables.md.\n");
-    functions.command("list").description("List the Function library, including draft and disabled Functions (up to 500).")
+        .description("Browse OXYGEN's ready-made Functions (work email, mobile phone, company funding stage, ...), favourite them, bind them to a table, or create, edit and publish your own Functions backed by ordinary Tables.")
+        .addHelpText("after", "\nOXYGEN-managed Functions are pre-built and priced: `functions list --managed` shows each one with its per-row credit estimate before you attach it. Attaching (`functions bind`) is free; only `columns run` spends, after a dry run. A managed Function is read-only; `functions duplicate <function>` gives you an editable copy.\nDraft edits are isolated. Publishing updates future invocations of every caller; queued, in-flight and past runs retain their captured version. Existing caller caps never increase automatically.\nFlow: draft → describe → publish → bind → columns run --dry-run → approved run → runs.\nA bound Function executes on its own published execution table and writes named outputs back to the calling table. The call stays visible from the caller: `table-runs list --table <caller> --status all` lists the run, and the binding column's cell holds the outcome (status, outputs, credits, invocation and run ids). Address a Function by id, slug, or the display name shown by `functions list`.\nWorked example with commands: `oxygen skills install --skill oxygen-gtm --project`, then read its recipes/callable-tables.md.\n");
+    functions.command("list").description("List the Function library: OXYGEN-managed Functions with their per-row credit estimate, plus your workspace's own drafts and published Functions (up to 500).")
+        .option("--managed", "Only OXYGEN-managed Functions (pre-built, priced, read-only; duplicate to customize).")
+        .option("--favorites", "Only the Functions you favourited (`functions favorite <function>`).")
         .option("--json", "Print a JSON envelope.")
-        .action((options) => handle("functions list", options, () => requestOxygen("/api/cli/functions")));
-    functions.command("describe <function>").description("Inspect a Function's draft, published version, inputs, outputs and credit caps.")
+        .action((options) => handle("functions list", options, () => {
+        if (options.managed && options.favorites)
+            throw new OxygenError("invalid_request", "Pass --managed or --favorites, not both.", { exitCode: 1 });
+        const filter = options.managed ? "managed" : options.favorites ? "favorites" : null;
+        return requestOxygen(filter ? `/api/cli/functions?${new URLSearchParams({ filter })}` : "/api/cli/functions");
+    }));
+    for (const [command, label] of [["favorite", "Favourite a Function so it appears under `functions list --favorites` and the Favorites tab; per user, per workspace."], ["unfavorite", "Remove a Function from your favourites."]]) {
+        functions.command(`${command} <function>`).description(label)
+            .option("--json", "Print a JSON envelope.")
+            .action((ref, options) => handle(`functions ${command}`, options, () => requestOxygen("/api/cli/functions", { method: "POST", body: { operation: command, function: ref } })));
+    }
+    functions.command("duplicate <function>").description("Copy a Function's steps into a new editable draft of your own (same inputs and outputs, no rows). The way to customize an OXYGEN-managed Function.")
+        .option("--name <name>", "Display name for the copy. Defaults to '<source> (copy)'.")
+        .option("--json", "Print a JSON envelope.")
+        .action((ref, options) => handle("functions duplicate", options, () => requestOxygen("/api/cli/functions", { method: "POST", body: { operation: "duplicate", function: ref, ...(options.name ? { display_name: options.name } : {}) } })));
+    functions.command("describe <function>").description("Inspect a Function's inputs, outputs, steps, per-row credit estimate, caps, and whether it is OXYGEN-managed or your own draft/published version.")
         .option("--json", "Print a JSON envelope.")
         .action((ref, options) => handle("functions describe", options, () => requestOxygen(`/api/cli/functions?${new URLSearchParams({ function: ref })}`)));
     functions.command("draft [function]").description("Create a Function draft, or save an existing Function's draft; executes nothing.")

package/dist/help.d.ts

@@ -1,2 +1,23 @@
 import type { Command } from "commander";
 export declare function applyOxygenHelp(program: Command, binaryName: string): void;
+/**
+ * Turn commander's own edit-distance suggester on for EVERY command.
+ *
+ * It defaults to on, but `copyInheritedSettings` only runs for children created
+ * through `.command()`; the hundreds of subcommands this CLI registers with
+ * `.addCommand(new Command(...))` carry whatever their own constructor set.
+ * Walking the tree makes the setting a property of the whole surface rather
+ * than of how each command happened to be built, the same reason
+ * `installCommanderExitOverride` recurses.
+ */
+export declare function enableCommandSuggestions(command: Command): void;
+/**
+ * The extra line printed after `error: unknown command '<x>'`.
+ *
+ * Commander's message names what is wrong and nothing a user can do next. This
+ * resolves the command they were actually inside, offers the synonym or unique
+ * prefix match commander cannot reach, and always names the exact `--help` that
+ * lists the real subcommands. Returns null when argv does not describe an
+ * unknown subcommand (an unknown OPTION has its own handling).
+ */
+export declare function unknownCommandHint(program: Command, argv: readonly string[]): string | null;

package/dist/help.js

@@ -139,6 +139,10 @@ export function applyOxygenHelp(program, binaryName) {
         `  2. ${binaryName} skills install --json      load the skills that teach the GTM loops (automatic after login)`,
         "     Add --project to keep the skills inside the current project, including confined agent sessions.",
         `  3. ${binaryName} context resolve --json     load workspace context before operating primitives`,
+        // A new workspace's first sessions are onboarding, and the consultant guide is
+        // a served skill an agent has to be TOLD about: nothing else on a first-touch
+        // surface named it (blind eval, 2026-09-16).
+        `     New or thin workspace? load the onboarding consultant first: ${binaryName} skills get oxygen-onboarding --json`,
         `  4. ${binaryName} capabilities search "<goal>" --json   route the goal, then hydrate one exact command`,
         `     ${binaryName} commands search "<term>" --json         find a command by name or purpose instead of dumping the manifest`,
         `  5. ${binaryName} recipes list --json       choose a play from the Recipe catalog for your goal`,
@@ -155,3 +159,92 @@ export function applyOxygenHelp(program, binaryName) {
         `Exit codes: ${exitCodeLine}`,
     ].join("\n"));
 }
+/**
+ * Turn commander's own edit-distance suggester on for EVERY command.
+ *
+ * It defaults to on, but `copyInheritedSettings` only runs for children created
+ * through `.command()`; the hundreds of subcommands this CLI registers with
+ * `.addCommand(new Command(...))` carry whatever their own constructor set.
+ * Walking the tree makes the setting a property of the whole surface rather
+ * than of how each command happened to be built, the same reason
+ * `installCommanderExitOverride` recurses.
+ */
+export function enableCommandSuggestions(command) {
+    command.showSuggestionAfterError(true);
+    for (const child of command.commands)
+        enableCommandSuggestions(child);
+}
+/**
+ * Verbs a user reaches for that this CLI spells differently.
+ *
+ * Commander's suggester is edit distance only, so it fires for a typo
+ * (`describ` → `describe`) and never for a synonym: `get` is seven edits from
+ * `describe`, so `oxygen tables get` answered `error: unknown command 'get'`
+ * and stopped there with nothing to try next (blind user eval, 2026-09-17).
+ * Values are candidate real subcommand names, best first; only names the
+ * command actually has are ever offered.
+ */
+const COMMAND_SYNONYMS = {
+    get: ["describe", "show", "view", "status", "preview"],
+    show: ["describe", "get", "list", "preview"],
+    view: ["describe", "preview", "show", "get"],
+    info: ["describe", "status", "show"],
+    inspect: ["describe", "preview", "show"],
+    read: ["describe", "query", "export", "get"],
+    ls: ["list"],
+    all: ["list"],
+    new: ["create", "add"],
+    make: ["create", "add"],
+    rm: ["delete", "remove", "archive"],
+    del: ["delete", "remove", "archive"],
+    remove: ["delete", "archive"],
+    destroy: ["delete", "archive"],
+    edit: ["update", "set", "rename"],
+    modify: ["update", "set"],
+    exec: ["run", "start", "call"],
+    execute: ["run", "start", "call"],
+    find: ["search", "query", "list"],
+};
+/**
+ * The extra line printed after `error: unknown command '<x>'`.
+ *
+ * Commander's message names what is wrong and nothing a user can do next. This
+ * resolves the command they were actually inside, offers the synonym or unique
+ * prefix match commander cannot reach, and always names the exact `--help` that
+ * lists the real subcommands. Returns null when argv does not describe an
+ * unknown subcommand (an unknown OPTION has its own handling).
+ */
+export function unknownCommandHint(program, argv) {
+    let current = program;
+    let path = program.name();
+    for (const token of argv) {
+        // Options and their values are commander's business; only the command path
+        // is walked here.
+        if (token.startsWith("-"))
+            break;
+        const child = current.commands.find((candidate) => candidate.name() === token || candidate.aliases().includes(token));
+        if (child) {
+            current = child;
+            path = `${path} ${token}`;
+            continue;
+        }
+        if (current.commands.length === 0)
+            return null;
+        return buildUnknownCommandHint(current, path, token);
+    }
+    return null;
+}
+function buildUnknownCommandHint(parent, path, token) {
+    const names = parent.commands.map((command) => command.name()).filter((name) => name !== "help");
+    const lower = token.toLowerCase();
+    const synonym = (COMMAND_SYNONYMS[lower] ?? []).find((candidate) => names.includes(candidate));
+    // A unique prefix is the other guess commander cannot make: `tables desc`
+    // scores too far from `describe` on edit distance, but it names exactly one
+    // command.
+    const prefixMatches = names.filter((name) => name.startsWith(lower));
+    const suggestion = synonym ?? (prefixMatches.length === 1 ? prefixMatches[0] : null);
+    const helpLine = `Run \`${path} --help\` for the ${names.length} subcommands of \`${path}\`.`;
+    return suggestion
+        ? `Hint: \`${path}\` has no \`${token}\`. Did you mean \`${path} ${suggestion}\`? ${helpLine}`
+        : `Hint: \`${path}\` has no \`${token}\`. ${helpLine}`;
+}