@skrr-ai/cli 0.1.92 → 0.1.93

package/dist/base-command.d.ts

@@ -43,7 +43,15 @@ export declare abstract class BaseCommand extends Command {
         token: Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
         workspace: Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
         profile: Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
+        raw: Interfaces.BooleanFlag<boolean>;
     };
+    /**
+     * JSON output goes through here, so the storage fields (`_id` beside `id`,
+     * `__v`) are dropped in ONE place and only at the CLI serializer (P9).
+     * `--raw` / `OVERSKY_CLI_RAW=1` opts out.
+     */
+    log(message?: string, ...args: unknown[]): void;
+    protected wantsRawJson(): boolean;
     protected cliConfig: CliConfig;
     /**
      * Resolved credential for this process. Populated in `init()` and
@@ -146,6 +154,22 @@ export declare abstract class BaseCommand extends Command {
      * server resolves the latter itself — so existing callers keep their
      * behavior and their request count. Only a title reaches the search.
      */
+    /**
+     * The ONE way a positional ID argument becomes the id a request carries
+     * (audit P7). `tasks show` resolved titles and refs while `tasks delete`,
+     * `tasks archive` and `spaces update` sent the raw string and relied on the
+     * server happening to accept it, so the same `OSK-12` worked on one verb and
+     * 404ed on the next. A command that takes a task, space or project reference
+     * calls this (or one of the three it delegates to) and nothing else;
+     * `entity-ref-resolution.spec.ts` fails on a new command that does not.
+     *
+     * `project` returns the project ref only: a project is addressed inside a
+     * space, so a command that needs the space too calls
+     * `resolveProjectReference` directly.
+     */
+    protected resolveEntityRef(kind: 'task' | 'space' | 'project', value: string, opts?: {
+        space?: string;
+    }): Promise<string>;
     protected resolveTaskReference(value: string): Promise<string>;
     /**
      * Parse flags, then resolve any `--space` reference to an id.
@@ -344,7 +368,14 @@ export declare abstract class BaseCommand extends Command {
      * bug (2026-09-18).
      */
     private lastApiRequestId?;
+    /** E6: the server's `Retry-After` for the refused call, when it was a 429. */
+    private lastRetryAfterMs?;
     private writeJsonCliError;
+    /**
+     * Write a shaped list (see `lib/list-output.ts`) to stdout, or as NDJSON:
+     * rows on stdout, one `{"_meta":...}` line (paging, warnings) on stderr.
+     */
+    protected printList(shaped: unknown, ndjson: boolean): void;
     protected wantsJsonOutput(): boolean;
 }
 /**
@@ -488,4 +519,17 @@ export declare function isTypedServerRefusal(body: Record<string, unknown> | nul
  */
 export declare function isApplicationCodedUnavailable(status: number | undefined, body: Record<string, unknown> | null): boolean;
 export declare function isRetryableFailure(status: number | undefined, body: Record<string, unknown> | null): boolean;
+/**
+ * P6: a parse error used to say what was wrong and drop the remedy that text
+ * mode (and every domain error) carries. Adds `fix` (one imperative line an
+ * agent can act on) and, for a missing flag, `flag` — beside the unchanged
+ * `code`, so nothing that matched CLI_PARSE_ERROR breaks.
+ */
+export declare function parseErrorRemedy(err: Error & {
+    code?: string;
+    suggestions?: unknown;
+}, commandId: string | undefined, bin?: string): {
+    fix?: string;
+    flag?: string;
+};
 export { Flags };

package/dist/base-command.js

@@ -17,10 +17,12 @@ exports.describeDaemonScopedCredential = describeDaemonScopedCredential;
 exports.isTypedServerRefusal = isTypedServerRefusal;
 exports.isApplicationCodedUnavailable = isApplicationCodedUnavailable;
 exports.isRetryableFailure = isRetryableFailure;
+exports.parseErrorRemedy = parseErrorRemedy;
 const node_fs_1 = require("node:fs");
 const core_1 = require("@oclif/core");
 Object.defineProperty(exports, "Flags", { enumerable: true, get: function () { return core_1.Flags; } });
 const option_hint_1 = require("./lib/option-hint");
+const json_output_1 = require("./lib/json-output");
 const failed_lookup_1 = require("./lib/failed-lookup");
 const internal_id_1 = require("./lib/internal-id");
 const http_error_1 = require("./lib/http-error");
@@ -33,6 +35,7 @@ Object.defineProperty(exports, "resolveProfileFromArgv", { enumerable: true, get
 const data_provider_1 = require("@skrr-ai/data-provider");
 const auth_core_1 = require("@skrr-ai/auth-core");
 const auth_failure_1 = require("./lib/auth-failure");
+const list_output_1 = require("./lib/list-output");
 const assignee_resolver_1 = require("./lib/assignee-resolver");
 const task_ref_resolver_1 = require("./lib/task-ref-resolver");
 const space_resolver_1 = require("./lib/space-resolver");
@@ -148,7 +151,25 @@ class BaseCommand extends core_1.Command {
                 'so signing into one does not sign you out of another. Also OVERSKY_PROFILE. ' +
                 'List them with `profiles list`.',
         }),
+        raw: core_1.Flags.boolean({
+            description: 'With --json, keep the Mongo storage fields (_id next to id, __v) that the CLI otherwise strips. Also OVERSKY_CLI_RAW=1.',
+            default: false,
+        }),
     };
+    /**
+     * JSON output goes through here, so the storage fields (`_id` beside `id`,
+     * `__v`) are dropped in ONE place and only at the CLI serializer (P9).
+     * `--raw` / `OVERSKY_CLI_RAW=1` opts out.
+     */
+    log(message, ...args) {
+        const text = typeof message === 'string' && this.wantsJsonOutput() && !this.wantsRawJson()
+            ? (0, json_output_1.stripStorageFieldsFromText)(message)
+            : message;
+        super.log(text, ...args);
+    }
+    wantsRawJson() {
+        return this.argv.includes('--raw') || process.env.OVERSKY_CLI_RAW === '1';
+    }
     cliConfig;
     /**
      * Resolved credential for this process. Populated in `init()` and
@@ -707,6 +728,26 @@ class BaseCommand extends core_1.Command {
      * server resolves the latter itself — so existing callers keep their
      * behavior and their request count. Only a title reaches the search.
      */
+    /**
+     * The ONE way a positional ID argument becomes the id a request carries
+     * (audit P7). `tasks show` resolved titles and refs while `tasks delete`,
+     * `tasks archive` and `spaces update` sent the raw string and relied on the
+     * server happening to accept it, so the same `OSK-12` worked on one verb and
+     * 404ed on the next. A command that takes a task, space or project reference
+     * calls this (or one of the three it delegates to) and nothing else;
+     * `entity-ref-resolution.spec.ts` fails on a new command that does not.
+     *
+     * `project` returns the project ref only: a project is addressed inside a
+     * space, so a command that needs the space too calls
+     * `resolveProjectReference` directly.
+     */
+    async resolveEntityRef(kind, value, opts = {}) {
+        if (kind === 'task')
+            return this.resolveTaskReference(value);
+        if (kind === 'space')
+            return this.resolveSpaceReference(value);
+        return (await this.resolveProjectReference(value, opts.space)).projectRef;
+    }
     async resolveTaskReference(value) {
         const direct = (0, task_ref_resolver_1.directTaskRef)(value);
         if (direct)
@@ -1066,6 +1107,7 @@ class BaseCommand extends core_1.Command {
                     retryable: err.retryable ?? false,
                     command: this.id ?? null,
                     server: this.cliConfig?.baseURL ?? null,
+                    ...parseErrorRemedy(err, this.id, this.config?.bin),
                     ...(details ? { details } : {}),
                 },
             }, null, 2));
@@ -1131,6 +1173,7 @@ class BaseCommand extends core_1.Command {
             // Remembered once here rather than threaded through every branch below:
             // each one ends in `failWithCliError`, and the id belongs on all of them.
             this.lastApiRequestId = e.requestId;
+            this.lastRetryAfterMs = e.retryAfterMs;
             const body = parseErrorBody(e.body);
             const bodyCode = stringProp(body, 'code') || stringProp(body, 'errorType');
             const bodyMessage = stringProp(body, 'message') || stringProp(body, 'error');
@@ -1715,6 +1758,8 @@ class BaseCommand extends core_1.Command {
      * bug (2026-09-18).
      */
     lastApiRequestId;
+    /** E6: the server's `Retry-After` for the refused call, when it was a 429. */
+    lastRetryAfterMs;
     writeJsonCliError({ message, code, status, exit, retryable, details, requestId, }) {
         this.log(JSON.stringify({
             ok: false,
@@ -1732,13 +1777,26 @@ class BaseCommand extends core_1.Command {
                 ...(requestId || this.lastApiRequestId
                     ? { requestId: requestId ?? this.lastApiRequestId }
                     : {}),
+                ...(this.lastRetryAfterMs !== undefined ? { retryAfterMs: this.lastRetryAfterMs } : {}),
                 ...(details ? { details } : {}),
             },
         }, null, 2));
         this.exit(exit);
     }
+    /**
+     * Write a shaped list (see `lib/list-output.ts`) to stdout, or as NDJSON:
+     * rows on stdout, one `{"_meta":...}` line (paging, warnings) on stderr.
+     */
+    printList(shaped, ndjson) {
+        const out = (0, list_output_1.renderListOutput)(shaped, ndjson);
+        for (const line of out.stdout)
+            this.log(line);
+        for (const line of out.stderr)
+            process.stderr.write(`${line}\n`);
+    }
     wantsJsonOutput() {
         return (this.argv.includes('--json') ||
+            this.argv.includes('--ndjson') ||
             process.env.SKY_JSON === '1' ||
             process.env.OVERSKY_CLI_JSON === '1');
     }
@@ -2271,6 +2329,44 @@ function retiredFlagHint(message) {
         return null;
     return hits.map((flag) => `  ${RETIRED_FLAG_REPLACEMENTS[flag]}`).join('\n');
 }
+/**
+ * P6: a parse error used to say what was wrong and drop the remedy that text
+ * mode (and every domain error) carries. Adds `fix` (one imperative line an
+ * agent can act on) and, for a missing flag, `flag` — beside the unchanged
+ * `code`, so nothing that matched CLI_PARSE_ERROR breaks.
+ */
+function parseErrorRemedy(err, commandId, bin = 'skrr') {
+    if (err.code)
+        return {};
+    const helpCommand = `${bin} ${(commandId ?? '').replace(/:/g, ' ')} --help`.replace(/\s+/g, ' ');
+    const message = err.message || '';
+    const suggestion = Array.isArray(err.suggestions)
+        ? err.suggestions.find((s) => typeof s === 'string')
+        : undefined;
+    const missingFlag = /Missing required flag[s]?:?\s*(?:\n\s*)?-{0,2}([a-z][\w-]*)/i.exec(message);
+    if (missingFlag) {
+        const flag = missingFlag[1];
+        return {
+            flag,
+            fix: suggestion ??
+                `Pass --${flag} <value>. Run \`${helpCommand}\` for its description and accepted values.`,
+        };
+    }
+    const nonexistent = /Nonexistent flag[s]?:?\s*(-{1,2}[\w-]+)/i.exec(message);
+    if (nonexistent) {
+        return {
+            flag: nonexistent[1].replace(/^-+/, ''),
+            fix: suggestion ??
+                `Remove ${nonexistent[1]}, or run \`${helpCommand}\` for the flags this command takes.`,
+        };
+    }
+    if (/Missing \d+ required arg/i.test(message)) {
+        return {
+            fix: suggestion ?? `Supply the missing argument. Run \`${helpCommand}\` for the usage line.`,
+        };
+    }
+    return { fix: suggestion ?? `Run \`${helpCommand}\` for usage.` };
+}
 function parseCliErrorCode(err) {
     if (err.name && err.name !== 'Error') {
         return err.name.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase();

package/dist/commands/agents/badge.d.ts

@@ -0,0 +1,41 @@
+import { BaseCommand } from '../../base-command';
+declare const FORMATS: readonly ["markdown", "html", "rst"];
+type BadgeFormat = (typeof FORMATS)[number];
+export type BadgeSnippetInput = {
+    name: string;
+    badgeUrl: string;
+    listingUrl: string;
+    installCommand: string;
+};
+/**
+ * The README snippet: the badge, linked to the attributed listing, then the
+ * one-line install. Pure, so the three formats are pinned by a test rather
+ * than by eye.
+ */
+export declare function badgeSnippet(format: BadgeFormat, input: BadgeSnippetInput): string;
+/**
+ * `skrr agents badge <agent>` — a README badge and install one-liner for a
+ * published agent.
+ *
+ * The badge IMAGE is served by the API (`/api/public/store/agents/:id/badge.svg`:
+ * anonymous, cacheable, public listings only), so it stays current as ratings
+ * and installs move and needs nothing committed beside the README. The badge
+ * LINK is the attributed listing URL on the `badge` channel, and the install
+ * line carries its own code on the `cli` channel, so the publisher's analytics
+ * can tell "clicked the badge" from "pasted the command". Both codes are the
+ * caller's, minted idempotently, so re-running this prints the same snippet.
+ */
+export default class AgentsBadge extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        agent: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        format: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        style: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}
+export {};

package/dist/commands/agents/badge.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.badgeSnippet = badgeSnippet;
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../base-command");
+const agent_ref_1 = require("../../lib/agent-ref");
+const agent_distribution_1 = require("../../lib/agent-distribution");
+const FORMATS = ['markdown', 'html', 'rst'];
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+/** Markdown link text: brackets and backslashes would end or bend the link. */
+function escapeMarkdownText(value) {
+    return value.replace(/[\\[\]]/g, (char) => `\\${char}`);
+}
+/**
+ * The README snippet: the badge, linked to the attributed listing, then the
+ * one-line install. Pure, so the three formats are pinned by a test rather
+ * than by eye.
+ */
+function badgeSnippet(format, input) {
+    const alt = `${data_provider_1.BRAND.displayName}: ${input.name}`;
+    switch (format) {
+        case 'html':
+            return [
+                `<a href="${escapeHtml(input.listingUrl)}"><img src="${escapeHtml(input.badgeUrl)}" alt="${escapeHtml(alt)}"></a>`,
+                '',
+                `<pre><code>${escapeHtml(input.installCommand)}</code></pre>`,
+            ].join('\n');
+        case 'rst':
+            return [
+                `.. image:: ${input.badgeUrl}`,
+                `   :target: ${input.listingUrl}`,
+                `   :alt: ${alt}`,
+                '',
+                '.. code-block:: sh',
+                '',
+                `   ${input.installCommand}`,
+            ].join('\n');
+        case 'markdown':
+        default:
+            return [
+                `[![${escapeMarkdownText(alt)}](${input.badgeUrl})](${input.listingUrl})`,
+                '',
+                '```sh',
+                input.installCommand,
+                '```',
+            ].join('\n');
+    }
+}
+/**
+ * `skrr agents badge <agent>` — a README badge and install one-liner for a
+ * published agent.
+ *
+ * The badge IMAGE is served by the API (`/api/public/store/agents/:id/badge.svg`:
+ * anonymous, cacheable, public listings only), so it stays current as ratings
+ * and installs move and needs nothing committed beside the README. The badge
+ * LINK is the attributed listing URL on the `badge` channel, and the install
+ * line carries its own code on the `cli` channel, so the publisher's analytics
+ * can tell "clicked the badge" from "pasted the command". Both codes are the
+ * caller's, minted idempotently, so re-running this prints the same snippet.
+ */
+class AgentsBadge extends base_command_1.BaseCommand {
+    static description = "Print a README badge (linked to the agent's Store listing) and a one-line install command for a published agent";
+    static examples = [
+        '<%= config.bin %> agents badge agent_abc123',
+        '<%= config.bin %> agents badge agent_abc123 --format html',
+        '<%= config.bin %> agents badge agent_abc123 --style flat-square --json',
+    ];
+    static args = {
+        agent: core_1.Args.string({
+            description: 'The published agent: its id or a link to it',
+            required: true,
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        format: core_1.Flags.string({
+            description: 'Snippet markup',
+            options: [...FORMATS],
+            default: 'markdown',
+        }),
+        style: core_1.Flags.string({
+            description: 'Badge look',
+            options: [...data_provider_1.STORE_BADGE_STYLES],
+            default: data_provider_1.STORE_BADGE_STYLES[0],
+        }),
+        json: core_1.Flags.boolean({
+            description: 'Print {agentId, name, badgeUrl, listingUrl, installCommand, snippet} as JSON',
+        }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(AgentsBadge);
+        const baseURL = this.cliConfig.baseURL;
+        let agentId;
+        try {
+            ({ agentId } = await (0, agent_ref_1.resolveAgentRef)(args.agent, { baseURL }));
+        }
+        catch (err) {
+            if (err instanceof agent_ref_1.AgentRefError) {
+                this.failWithCliError({ message: err.message, code: err.code, exit: 1, retryable: false });
+            }
+            this.handleApiError(err);
+        }
+        let listingLink;
+        let installLink;
+        try {
+            [listingLink, installLink] = await Promise.all([
+                (0, agent_distribution_1.mintAgentShareLink)({ baseURL, agentId, channel: 'badge' }),
+                (0, agent_distribution_1.mintAgentShareLink)({ baseURL, agentId, channel: 'cli' }),
+            ]);
+        }
+        catch (err) {
+            if (err instanceof agent_distribution_1.AgentNotShareableError) {
+                this.failWithCliError({ message: err.message, code: err.code, exit: 1, retryable: false });
+            }
+            this.handleApiError(err, { subject: `agent ${agentId}` });
+        }
+        // The name in the alt text is the public listing's (the released name),
+        // the same one the badge image draws. A failed read falls back to the id
+        // rather than failing a snippet whose image and links are already correct.
+        let name = agentId;
+        try {
+            name = (await data_provider_1.dataService.getPublicAgentListing(agentId)).name || agentId;
+        }
+        catch {
+            // keep the id
+        }
+        const badgeUrl = (0, agent_distribution_1.agentBadgeImageUrl)(agentId, flags.style);
+        const installCommand = `${this.config.bin} store install ${(0, agent_ref_1.shellQuote)(installLink.url)}`;
+        const snippet = badgeSnippet(flags.format, {
+            name,
+            badgeUrl,
+            listingUrl: listingLink.url,
+            installCommand,
+        });
+        if (flags.json) {
+            this.log(JSON.stringify({
+                agentId,
+                name,
+                badgeUrl,
+                listingUrl: listingLink.url,
+                installCommand,
+                format: flags.format,
+                snippet,
+            }, null, 2));
+            return;
+        }
+        this.log(snippet);
+    }
+}
+exports.default = AgentsBadge;

package/dist/commands/agents/create.d.ts

@@ -72,12 +72,21 @@ export declare function unappliedPayloadKeys(sent: Record<string, unknown>, crea
  */
 export declare function unappliedPayloadKeysWarning(keys: readonly string[]): string;
 export declare function backgroundLoopLines(agentId: string, relationshipLoopsSkipped: boolean): string[];
+/**
+ * The flags `--from-spec` may be combined with: placement and identity for the
+ * NEW row, which a spec document deliberately cannot carry (where an agent runs
+ * is not portable). Every configuration flag is refused alongside it, because
+ * the file is the source — a flag that quietly overrode a line of it would
+ * leave git and the agent disagreeing from the first push.
+ */
+export declare const FROM_SPEC_COMPATIBLE_FLAGS: readonly string[];
 export default class AgentsCreate extends BaseCommand {
     static description: string;
     static examples: string[];
     static flags: {
         json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         'from-json': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'from-spec': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         name: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         description: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         provider: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
@@ -124,4 +133,19 @@ export default class AgentsCreate extends BaseCommand {
         'auto-minor-updates': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
+    /**
+     * `agents create --from-spec <file>`: bootstrap a NEW agent from an
+     * agent-as-code document, so a repository can hold an agent before one
+     * exists (`agents push` needs an existing id).
+     *
+     * Two writes, one writer per concern. The create carries only what makes a
+     * row — its name, provider, model and placement — and every other field
+     * reaches the agent through the push endpoint, so the document is held to
+     * exactly the rules `agents push` and `agents validate` apply (portable
+     * fields only, no credentials, no withheld references, nothing push may not
+     * set). Validation runs first with no network. If the server then refuses
+     * the document, the agent just created is deleted again: a refused spec must
+     * not leave behind a half-configured agent that looks like it worked.
+     */
+    private createFromSpec;
 }