@skrr-ai/cli 0.1.118 → 0.1.120

package/dist/commands/tasks/watch.js

@@ -4,12 +4,15 @@ const core_1 = require("@oclif/core");
 const base_command_1 = require("../../base-command");
 const format_1 = require("../../lib/format");
 const task_execution_1 = require("../../lib/task-execution");
+const task_operation_watch_1 = require("../../lib/task-operation-watch");
+const data_provider_1 = require("@skrr-ai/data-provider");
 class TasksWatch extends base_command_1.BaseCommand {
-    static description = 'Watch task execution status until completion or failure';
+    static description = 'Watch task execution status, or one immutable Task Operation, without dispatching work';
     static examples = [
         '<%= config.bin %> tasks watch <task-id>',
         '<%= config.bin %> tasks watch <root-task-id> --descendants',
         '<%= config.bin %> tasks watch <root-task-id> --descendants --json',
+        '<%= config.bin %> tasks watch <task-id> --operation <operation-id> --timeout 10m',
     ];
     static args = {
         id: core_1.Args.string({ description: 'Task or root task ID', required: true, ignoreStdin: true }),
@@ -27,14 +30,27 @@ class TasksWatch extends base_command_1.BaseCommand {
         interval: core_1.Flags.integer({ description: 'Polling interval in seconds', default: 5 }),
         timeout: core_1.Flags.string({ description: 'Timeout such as 30s, 10m, 2h' }),
         limit: core_1.Flags.integer({ description: 'Max descendants to inspect', default: 500 }),
+        operation: core_1.Flags.string({
+            description: 'Watch this immutable Task Operation rather than inferring completion from Task workflow status',
+        }),
     };
     async run() {
         this.requireAuth();
         const { args, flags } = await this.parse(TasksWatch);
+        if (flags.operation) {
+            if (flags.descendants ||
+                flags['children-only'] ||
+                (flags['fail-on'] !== undefined && flags['fail-on'] !== task_execution_1.DEFAULT_FAIL_STATUSES_FLAG) ||
+                (flags.limit !== undefined && flags.limit !== 500)) {
+                this.error('--operation cannot be combined with --descendants, --children-only, --fail-on, or --limit. It watches one immutable operation, not a Task tree.', { exit: 2 });
+            }
+            await this.watchOperation(args.id, flags.operation, flags);
+            return;
+        }
         const failOn = (0, task_execution_1.parseStatusSet)(flags['fail-on'], task_execution_1.DEFAULT_FAIL_STATUSES);
         let timeoutMs = null;
         try {
-            timeoutMs = parseDurationMs(flags.timeout);
+            timeoutMs = (0, task_operation_watch_1.parseTaskOperationWatchDuration)(flags.timeout);
         }
         catch (err) {
             this.error(err.message, { exit: 1 });
@@ -76,6 +92,73 @@ class TasksWatch extends base_command_1.BaseCommand {
             await (0, task_execution_1.sleep)(intervalMs);
         }
     }
+    async watchOperation(taskRef, operationId, flags) {
+        const taskId = await this.resolveTaskReference(taskRef);
+        const canonicalOperationId = operationId.trim();
+        if (!canonicalOperationId || canonicalOperationId.length > 200) {
+            this.error('--operation must be a non-empty operation ID of at most 200 characters.', { exit: 2 });
+            return;
+        }
+        let timeoutMs;
+        try {
+            timeoutMs = (0, task_operation_watch_1.parseTaskOperationWatchDuration)(flags.timeout);
+        }
+        catch (error) {
+            this.error(error.message, { exit: 2 });
+            return;
+        }
+        const intervalMs = Math.max(1, flags.interval) * 1000;
+        const getTaskOperation = data_provider_1.dataService.getTaskOperation;
+        if (!getTaskOperation) {
+            this.failWithCliError({
+                code: 'TASK_OPERATION_READER_UNAVAILABLE',
+                message: 'This CLI build cannot read Task Operations. Update skrr before waiting on this operation.',
+                exit: 2,
+                retryable: false,
+            });
+        }
+        try {
+            const result = await (0, task_operation_watch_1.watchTaskOperation)({
+                taskId,
+                operationId: canonicalOperationId,
+                intervalMs,
+                timeoutMs,
+                read: getTaskOperation,
+                onCheckpoint: (checkpoint) => this.printOperationCheckpoint(checkpoint, Boolean(flags.json)),
+            });
+            if (result.result === 'failed')
+                this.exit(1);
+        }
+        catch (error) {
+            const candidate = error;
+            if (candidate?.code === 'TASK_OPERATION_WAIT_TIMEOUT') {
+                this.exit(124);
+                return;
+            }
+            if (candidate?.code === 'TASK_OPERATION_TERMINAL_UNKNOWN') {
+                this.failWithCliError({
+                    code: 'TASK_OPERATION_TERMINAL_UNKNOWN',
+                    message: 'The Task Operation is terminal but does not report a recognized outcome. Inspect it; do not issue a fresh operation by guesswork.',
+                    exit: 2,
+                    retryable: false,
+                    details: { operationId: canonicalOperationId, taskId },
+                });
+                return;
+            }
+            this.handleApiError(error, { subject: `Task operation ${canonicalOperationId}` });
+        }
+    }
+    printOperationCheckpoint(checkpoint, json) {
+        if (json) {
+            this.log(JSON.stringify(checkpoint));
+            return;
+        }
+        // A text stream stays calm between changes; JSON preserves every polling
+        // checkpoint so automation can distinguish a live wait from silence.
+        if (checkpoint.changed || checkpoint.terminal || checkpoint.observation === 'timeout') {
+            this.log((0, task_operation_watch_1.taskOperationCheckpointLine)(checkpoint));
+        }
+    }
     printSnapshot(snapshot) {
         this.log('');
         this.log(`[${snapshot.generatedAt}] tasks=${snapshot.taskCount} active=${snapshot.activeCount} recovered=${snapshot.recoveredCount} terminal=${snapshot.terminalCount} pending=${snapshot.pendingCount}`);
@@ -101,21 +184,3 @@ class TasksWatch extends base_command_1.BaseCommand {
     }
 }
 exports.default = TasksWatch;
-function parseDurationMs(value) {
-    if (!value)
-        return null;
-    const match = value.trim().match(/^(\d+)(ms|s|m|h)?$/i);
-    if (!match)
-        throw new Error(`Invalid --timeout value: ${value}`);
-    const amount = Number(match[1]);
-    const unit = (match[2] || 's').toLowerCase();
-    if (unit === 'ms')
-        return amount;
-    if (unit === 's')
-        return amount * 1000;
-    if (unit === 'm')
-        return amount * 60 * 1000;
-    if (unit === 'h')
-        return amount * 60 * 60 * 1000;
-    return amount * 1000;
-}

package/dist/commands/wiki/history.d.ts

@@ -0,0 +1,33 @@
+import type { WikiPageAuthor, WikiPageRevision } from '@skrr-ai/data-provider';
+import { BaseCommand } from '../../base-command';
+/**
+ * `agent <id>` for a write a verified Run proved; otherwise the person whose
+ * credential wrote it, with the channel it came through — so an agent working
+ * through a delegated CLI credential without Run proof reads as
+ * "person <id> (via delegated agent CLI credential)", never as a bare person.
+ */
+export declare function formatAuthor(author: WikiPageAuthor | undefined): string;
+export declare function buildHistoryRows(revisions: WikiPageRevision[]): {
+    rev: string;
+    when: string;
+    author: string;
+    also: string;
+    source: string;
+    chars: string;
+}[];
+export default class WikiHistory extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        space: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        path: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'page-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        cursor: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        revision: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/wiki/history.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatAuthor = formatAuthor;
+exports.buildHistoryRows = buildHistoryRows;
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../base-command");
+const format_1 = require("../../lib/format");
+/**
+ * `agent <id>` for a write a verified Run proved; otherwise the person whose
+ * credential wrote it, with the channel it came through — so an agent working
+ * through a delegated CLI credential without Run proof reads as
+ * "person <id> (via delegated agent CLI credential)", never as a bare person.
+ */
+function formatAuthor(author) {
+    if (!author)
+        return 'unknown';
+    if (author.kind === 'agent')
+        return `agent ${author.agentId ?? '?'}`;
+    const channel = author.via
+        ? (data_provider_1.CREDENTIAL_CHANNEL_LABELS[author.via] ?? author.via)
+        : null;
+    return channel ? `person ${author.userId} (via ${channel})` : `person ${author.userId}`;
+}
+function sameAuthor(a, b) {
+    return (a.kind === b.kind &&
+        a.userId === b.userId &&
+        a.agentId === b.agentId &&
+        a.runId === b.runId &&
+        a.via === b.via);
+}
+function buildHistoryRows(revisions) {
+    return revisions.map((revision) => {
+        const others = (revision.contributors ?? []).filter((contributor) => !revision.author || !sameAuthor(contributor, revision.author));
+        const source = revision.source === 'write'
+            ? `write${revision.mode ? `/${revision.mode}` : ''}`
+            : `editor${revision.open ? ' (open)' : ''}`;
+        return {
+            rev: String(revision.revisionNumber),
+            when: revision.capturedAt ?? revision.createdAt ?? '',
+            author: formatAuthor(revision.author),
+            also: others.map(formatAuthor).join(', '),
+            source,
+            chars: String(revision.chars ?? 0),
+        };
+    });
+}
+class WikiHistory extends base_command_1.BaseCommand {
+    static description = "Show a wiki page's revision history: each version, and whether a person or an agent wrote it";
+    static examples = [
+        '<%= config.bin %> wiki history <space-id> Engineering/Runbooks/deploy',
+        '<%= config.bin %> wiki history <space-id> Engineering/Runbooks/deploy --revision 3 > v3.md',
+        '<%= config.bin %> wiki history <space-id> --page-id <page-id> --json',
+    ];
+    static args = {
+        space: core_1.Args.string({ description: 'Space ID', required: true, ignoreStdin: true }),
+        path: core_1.Args.string({ description: 'Page path', required: false, ignoreStdin: true }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+        'page-id': core_1.Flags.string({ description: 'Address the page by id instead of path' }),
+        limit: core_1.Flags.integer({ description: 'Revisions per page (max 100)', default: 20 }),
+        cursor: core_1.Flags.string({ description: 'Continue from a previous listing (its next_cursor)' }),
+        revision: core_1.Flags.integer({
+            description: 'Print one revision as Markdown instead of listing them',
+            min: 1,
+        }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(WikiHistory);
+        if (!args.path && !flags['page-id']) {
+            this.failWithCliError({
+                message: 'Provide a page path or --page-id.',
+                code: 'WIKI_PAGE_ADDRESS_REQUIRED',
+                exit: 1,
+                retryable: false,
+            });
+        }
+        const pageId = flags['page-id'];
+        const path = args.path;
+        if (flags.revision !== undefined) {
+            let revision;
+            try {
+                revision = pageId
+                    ? await data_provider_1.dataService.getSpaceWikiPageRevision(args.space, pageId, flags.revision)
+                    : await data_provider_1.dataService.getSpaceWikiRevisionByPath(args.space, path, flags.revision);
+            }
+            catch (err) {
+                this.handleApiError(err);
+            }
+            if (flags.json) {
+                this.printJsonResult(revision);
+                return;
+            }
+            // Body only, like `wiki cat`, so `> v3.md` produces a clean file.
+            this.log(revision.content ?? '');
+            return;
+        }
+        let response;
+        const paging = { limit: flags.limit, cursor: flags.cursor };
+        try {
+            response = pageId
+                ? await data_provider_1.dataService.getSpaceWikiPageHistory(args.space, pageId, paging)
+                : await data_provider_1.dataService.getSpaceWikiHistoryByPath(args.space, path, paging);
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        if (flags.json) {
+            this.printJsonResult(response);
+            return;
+        }
+        const revisions = response.data ?? [];
+        if (revisions.length === 0) {
+            // History starts with the first write recorded after it shipped; an
+            // older page has none until it is next edited.
+            this.log('No recorded revisions yet.');
+            return;
+        }
+        (0, format_1.renderTable)(buildHistoryRows(revisions), [
+            { key: 'rev', header: 'REV' },
+            { key: 'when', header: 'WHEN', maxWidth: 24 },
+            { key: 'author', header: 'AUTHOR', maxWidth: 60 },
+            { key: 'also', header: 'ALSO', maxWidth: 60 },
+            { key: 'source', header: 'SOURCE' },
+            { key: 'chars', header: 'CHARS' },
+        ], (line) => this.log(line));
+        if (response.has_more && response.next_cursor) {
+            this.log(`More: --cursor ${response.next_cursor}`);
+        }
+    }
+}
+exports.default = WikiHistory;

package/dist/commands/wiki/ls.d.ts

@@ -5,6 +5,8 @@ export type WikiLsRow = {
     kind: string;
     name: string;
     title: string;
+    /** A page's kind when it is not an ordinary `doc` page (`charter`, ...); '' otherwise. */
+    pageKind: string;
     updated: string;
     id: string;
 };

package/dist/commands/wiki/ls.js

@@ -20,6 +20,7 @@ function buildRows(listing) {
             // title would just repeat it. The listing carries no folder timestamp, so
             // it has no date to show either.
             title: '',
+            pageKind: '',
             updated: '',
             id: f.folder_id,
         })),
@@ -32,6 +33,9 @@ function buildRows(listing) {
             // `tree` has always rendered `slug [title]`; `ls` simply had no column
             // for it, though `--json` carried it all along.
             title: p.title && p.title !== p.slug ? p.title : '',
+            // Only a page that is not an ordinary doc names its kind (OSK-17985).
+            // A server that predates kinds sends none, which reads as `doc`.
+            pageKind: p.kind && p.kind !== 'doc' ? p.kind : '',
             updated: (0, format_1.localStamp)(p.lastEditedAt ?? p.updatedAt) || '',
             id: p.pageId,
         })),
@@ -39,6 +43,7 @@ function buildRows(listing) {
             kind: 'file',
             name: f.filename,
             title: '',
+            pageKind: '',
             updated: '',
             id: f.file_id,
         })),
@@ -58,6 +63,9 @@ function columnsFor(rows) {
     ];
     if (rows.some((r) => r.title))
         columns.push({ key: 'title', header: 'TITLE', maxWidth: 48 });
+    // Elided like TITLE: a wiki of ordinary pages prints exactly what it did.
+    if (rows.some((r) => r.pageKind))
+        columns.push({ key: 'pageKind', header: 'KIND' });
     // The thing most worth knowing from a listing is what moved recently, and
     // `ls` gave a UUID nobody asked for and no date at all.
     if (rows.some((r) => r.updated))

package/dist/commands/wiki/update.d.ts

@@ -1,6 +1,7 @@
 import { BaseCommand } from '../../base-command';
 /**
- * `skrr wiki update <space> <path>` — a page's METADATA: title, icon, order.
+ * `skrr wiki update <space> <path>` — a page's METADATA: title, icon, order,
+ * kind.
  *
  * Distinct from `mv`, which owns the page's PATH, and from `write`, which owns
  * its body. That split follows the server: retitling deliberately keeps the
@@ -21,6 +22,7 @@ export default class WikiUpdate extends BaseCommand {
         icon: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'clear-icon': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         order: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        kind: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;

package/dist/commands/wiki/update.js

@@ -3,10 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
+const space_charter_1 = require("../../lib/space-charter");
 const wiki_1 = require("../../lib/wiki");
 const wiki_update_1 = require("../../lib/wiki-update");
 /**
- * `skrr wiki update <space> <path>` — a page's METADATA: title, icon, order.
+ * `skrr wiki update <space> <path>` — a page's METADATA: title, icon, order,
+ * kind.
  *
  * Distinct from `mv`, which owns the page's PATH, and from `write`, which owns
  * its body. That split follows the server: retitling deliberately keeps the
@@ -16,12 +18,16 @@ const wiki_update_1 = require("../../lib/wiki-update");
  * `mv` is for, and two commands that both rewrite a slug is how they drift.
  */
 class WikiUpdate extends base_command_1.BaseCommand {
-    static description = "Update a wiki page's title, icon, or sort order";
+    static description = "Update a wiki page's title, icon, sort order, or kind. A Space holds at most one " +
+        'live charter page: making a second page the charter is refused until the first ' +
+        'is changed to another kind or archived.';
     static examples = [
         '<%= config.bin %> wiki update <space-id> Engineering/deploy --title "Deploy Runbook"',
         '<%= config.bin %> wiki update <space-id> Engineering/deploy --icon 🚀',
         '<%= config.bin %> wiki update <space-id> Engineering/deploy --clear-icon',
         '<%= config.bin %> wiki update <space-id> Engineering/deploy --order 0 --json',
+        '<%= config.bin %> wiki update <space-id> charter --kind charter',
+        '<%= config.bin %> wiki update <space-id> journal/2026-10-22 --kind journal_entry',
     ];
     static args = {
         space: core_1.Args.string({ description: 'Space ID', required: true, ignoreStdin: true }),
@@ -37,6 +43,11 @@ class WikiUpdate extends base_command_1.BaseCommand {
             exclusive: ['icon'],
         }),
         order: core_1.Flags.integer({ description: 'Sort position within its folder (0-based)' }),
+        kind: core_1.Flags.string({
+            description: "What the page is for. `charter` is the Space's one charter (its lead section, " +
+                'before the first ## heading, is read by every agent in the Space).',
+            options: [...data_provider_1.WIKI_PAGE_KINDS],
+        }),
         json: core_1.Flags.boolean({ description: 'Output as JSON' }),
     };
     async run() {
@@ -56,6 +67,7 @@ class WikiUpdate extends base_command_1.BaseCommand {
             icon: flags.icon,
             clearIcon: flags['clear-icon'],
             order: flags.order,
+            kind: flags.kind,
         });
         if (!built.ok) {
             this.failWithCliError({
@@ -82,6 +94,16 @@ class WikiUpdate extends base_command_1.BaseCommand {
             });
         }
         catch (err) {
+            const hint = (0, space_charter_1.charterConflictHint)(err, { binName: this.config.bin, spaceId: args.space });
+            if (hint) {
+                this.failWithCliError({
+                    message: hint.message,
+                    code: 'WIKI_CHARTER_EXISTS',
+                    exit: 1,
+                    retryable: false,
+                    details: hint.details,
+                });
+            }
             this.handleApiError(err, { subject: `wiki page ${path}` });
         }
         if (flags.json) {

package/dist/commands/wiki/write.d.ts

@@ -35,6 +35,23 @@ export declare function slugifyLikeServer(input: string): string;
  * later reads as "no collision" rather than as a fresh false positive.
  */
 export declare function createdSlugCollided(requestedSlug: string, createdSlug?: string): boolean;
+/**
+ * The warning for `--kind` on a write that landed in a page that already
+ * existed, or `null` when there is nothing to say.
+ *
+ * `--kind`, like `--title`, describes a page this command CREATES: `write` owns
+ * the body, `update` owns metadata. A write into an existing page of another
+ * kind therefore changes the body and not the kind, and saying so is the
+ * difference between that and a silent no-op. A page an older server returns
+ * without a kind reads as `doc`.
+ */
+export declare function kindIgnoredWarning(opts: {
+    requested?: string;
+    existingKind?: string;
+    binName: string;
+    spaceId: string;
+    path: string;
+}): string | null;
 export default class WikiWrite extends BaseCommand {
     static description: string;
     static examples: string[];
@@ -49,7 +66,12 @@ export default class WikiWrite extends BaseCommand {
         stdin: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         html: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         append: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'create-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         title: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        kind: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        section: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        lead: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        note: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }