@skrr-ai/cli 0.1.118 → 0.1.120

package/dist/commands/wiki/write.js

@@ -4,10 +4,12 @@ exports.isWikiPageNotFound = isWikiPageNotFound;
 exports.conflictingPageId = conflictingPageId;
 exports.slugifyLikeServer = slugifyLikeServer;
 exports.createdSlugCollided = createdSlugCollided;
+exports.kindIgnoredWarning = kindIgnoredWarning;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
 const http_error_1 = require("../../lib/http-error");
+const space_charter_1 = require("../../lib/space-charter");
 const web_url_1 = require("../../lib/web-url");
 const wiki_1 = require("../../lib/wiki");
 /**
@@ -90,6 +92,27 @@ function createdSlugCollided(requestedSlug, createdSlug) {
     // fallback, an 8-char uuid head.
     return /^\d+$/.test(suffix) || /^[0-9a-f]{8}$/.test(suffix);
 }
+/**
+ * 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`.
+ */
+function kindIgnoredWarning(opts) {
+    const { requested, existingKind, binName, spaceId, path } = opts;
+    if (requested === undefined)
+        return null;
+    const actual = (0, data_provider_1.readWikiPageKind)(existingKind);
+    if (actual === requested)
+        return null;
+    return (`--kind was ignored: '${path}' already exists as a ${actual} page, and \`wiki write\` only sets ` +
+        `the kind of pages it creates. Change it with \`${binName} wiki update ${spaceId} ${path} ` +
+        `--kind ${requested}\`.`);
+}
 class WikiWrite extends base_command_1.BaseCommand {
     // The markdown dialect note lives here, not only in SKRR_WIKI.md: --help is the
     // one place a CLI user (or an agent with no docs) looks before writing, and
@@ -118,6 +141,11 @@ class WikiWrite extends base_command_1.BaseCommand {
         '<%= config.bin %> wiki write <space-id> Engineering/deploy --file runbook.md',
         'cat notes.md | <%= config.bin %> wiki write <space-id> notes --stdin',
         '<%= config.bin %> wiki write <space-id> log --content "Shipped v2" --append',
+        '<%= config.bin %> wiki write <space-id> charter --kind charter --file charter.md',
+        '<%= config.bin %> wiki write <space-id> journal/2026-10-22 --kind journal_entry --stdin',
+        '<%= config.bin %> wiki write <space-id> Reviews/2026-w43 --kind report --create-only --stdin',
+        '<%= config.bin %> wiki write <space-id> charter --section "## Goals" --file goals.md --note "Tighter after the KR review"',
+        '<%= config.bin %> wiki write <space-id> charter --lead --file lead.md',
     ];
     static args = {
         space: core_1.Args.string({ description: 'Space ID', required: true, ignoreStdin: true }),
@@ -130,9 +158,33 @@ class WikiWrite extends base_command_1.BaseCommand {
         stdin: core_1.Flags.boolean({ description: 'Read content from stdin' }),
         html: core_1.Flags.boolean({ description: 'Treat the input as HTML instead of Markdown' }),
         append: core_1.Flags.boolean({ description: 'Append instead of replacing (>> rather than >)' }),
+        'create-only': core_1.Flags.boolean({
+            description: 'Create a new page only. Refuse an existing path or a create race without replacing its content',
+            exclusive: ['append', 'section', 'lead'],
+        }),
         title: core_1.Flags.string({
             description: 'Title for a NEWLY-CREATED page (defaults to the slug). Retitle an existing page with `wiki update --title`',
         }),
+        kind: core_1.Flags.string({
+            description: 'Kind for a NEWLY-CREATED page (default doc). A Space holds one live `charter`; its lead ' +
+                'section is read by every agent in the Space. Change an existing page with `wiki update --kind`',
+            options: [...data_provider_1.WIKI_PAGE_KINDS],
+        }),
+        section: core_1.Flags.string({
+            description: 'Replace ONE section of an existing page instead of the whole page: a heading line ' +
+                '(`## Goals`, which also fixes the level) or its text. The content replaces the heading and ' +
+                'everything under it, up to the next heading of the same or a higher level, so include the heading',
+            exclusive: ['lead', 'append'],
+        }),
+        lead: core_1.Flags.boolean({
+            description: 'Replace only the lead of an existing page: everything before its first `##` heading (for a ' +
+                'charter, the part every agent in the Space reads)',
+            exclusive: ['section', 'append'],
+        }),
+        note: core_1.Flags.string({
+            description: 'Why you are making the change. When the Space holds the write for approval it becomes a ' +
+                'suggestion on the page, and this is its first comment; otherwise it is not stored',
+        }),
     };
     async run() {
         this.requireAuth();
@@ -155,9 +207,10 @@ class WikiWrite extends base_command_1.BaseCommand {
         }
         const format = flags.html ? 'html' : 'markdown';
         const mode = flags.append ? 'append' : 'replace';
-        // Create-or-write, so an agent never has to branch on existence. Look the
-        // page up first; a 404 means "create it", which also creates the folder
-        // chain via `folderPath` (mkdir -p).
+        const partial = flags.section !== undefined || flags.lead === true;
+        // Create-or-write by default; --create-only refuses the existing branch.
+        // A lookup 404 means "create it", which also creates the folder chain via
+        // `folderPath` (mkdir -p). The server's conflict check below owns the race.
         let existing = null;
         try {
             existing = await data_provider_1.dataService.getSpaceWikiPageByPath(args.space, args.path);
@@ -167,17 +220,47 @@ class WikiWrite extends base_command_1.BaseCommand {
                 this.handleApiError(err);
             }
         }
+        if (flags['create-only'] && existing) {
+            this.failWithCliError({
+                message: `Page '${args.path}' already exists (${existing.pageId}); --create-only changed nothing.`,
+                code: 'WIKI_PAGE_EXISTS',
+                status: 409,
+                exit: 1,
+                retryable: false,
+                details: { requestedPath: args.path, pageId: existing.pageId },
+            });
+        }
+        // A section or the lead is a part of a page that exists: there is nothing
+        // to create it in.
+        if (partial && !existing) {
+            this.failWithCliError({
+                message: `No page at '${args.path}' to replace ${flags.lead ? 'the lead of' : 'a section of'}. ` +
+                    'Write the whole page first.',
+                code: 'WIKI_PAGE_NOT_FOUND',
+                status: 404,
+                exit: 1,
+                retryable: false,
+            });
+        }
         const { dir, name } = (0, wiki_1.splitParentPath)(args.path);
         const writeInto = (pageId) => data_provider_1.dataService.writeSpaceWikiPageContent({
             spaceId: args.space,
             pageId,
-            data: { content, format, mode },
+            data: {
+                content,
+                format,
+                mode,
+                ...(flags.section !== undefined ? { section: flags.section } : {}),
+                ...(flags.lead ? { lead: true } : {}),
+                ...(flags.note ? { note: flags.note } : {}),
+            },
         });
         let page;
         // `existing` decides which branch we OPEN with, never which one we end in:
         // the lookup above can be stale (a CDN-cached 404 is the documented case),
         // so the create below asks the server to refuse rather than rename, and a
-        // refusal is resolved by writing into whatever was really there.
+        // refusal is normally resolved by writing into whatever was really there.
+        // --create-only preserves that refusal instead of changing the winner.
         let wroteIntoExisting = Boolean(existing);
         try {
             if (existing) {
@@ -193,6 +276,7 @@ class WikiWrite extends base_command_1.BaseCommand {
                             folderPath: dir || undefined,
                             content,
                             format,
+                            ...(flags.kind ? { kind: flags.kind } : {}),
                             // Never let the server rename an EXACTLY addressed path. Without
                             // this it answers 201 having created `x-2` beside `x`, and the
                             // write the user asked for silently did not happen.
@@ -202,7 +286,7 @@ class WikiWrite extends base_command_1.BaseCommand {
                 }
                 catch (err) {
                     const conflictId = conflictingPageId(err);
-                    if (conflictId === undefined) {
+                    if (conflictId === undefined || flags['create-only']) {
                         throw err;
                     }
                     // The page existed after all. This is the outcome the user asked
@@ -213,11 +297,50 @@ class WikiWrite extends base_command_1.BaseCommand {
             }
         }
         catch (err) {
+            const charterConflict = (0, space_charter_1.charterConflictHint)(err, {
+                binName: this.config.bin,
+                spaceId: args.space,
+            });
+            if (charterConflict) {
+                this.failWithCliError({
+                    message: charterConflict.message,
+                    code: 'WIKI_CHARTER_EXISTS',
+                    status: 409,
+                    exit: 1,
+                    retryable: false,
+                    details: charterConflict.details,
+                });
+            }
             this.handleApiError(err);
         }
+        // A write an unattended run makes may be held for approval by the Space's
+        // write policy (`202 pending_approval`): a journal entry or report create,
+        // or an append to the one it created (`--append`, OSK-17995), in its Run's
+        // approval bundle (OSK-17994); an edit of any other page's body as a
+        // suggestion on the page (OSK-17997). Nothing was written yet.
+        if (this.reportHeldSpaceWrite(page, { json: flags.json }))
+            return;
         // Fallback for a server predating `conflict: 'fail'`, which answers 201
         // with a renamed slug instead of 409. Unreachable against a current server.
         if (!wroteIntoExisting && createdSlugCollided(name, page.slug)) {
+            if (flags['create-only']) {
+                this.failWithCliError({
+                    message: `The server created '${page.path ?? page.slug}' (${page.pageId}) instead of '${args.path}'. ` +
+                        'This server did not honor atomic --create-only. The existing page was not replaced, ' +
+                        'and the newly created page has not been removed. Upgrade the server before retrying this operation.',
+                    code: 'WIKI_CREATE_ONLY_UNSUPPORTED',
+                    exit: 1,
+                    retryable: false,
+                    details: {
+                        outcome: 'created_different_path',
+                        requestedPath: args.path,
+                        requestedSlug: name,
+                        createdSlug: page.slug,
+                        createdPath: page.path,
+                        pageId: page.pageId,
+                    },
+                });
+            }
             this.failWithCliError({
                 message: `Wrote a DUPLICATE page: asked for '${args.path}' but the server already had that slug and created ` +
                     `'${page.path ?? page.slug}' (${page.pageId}) beside it. The content did NOT overwrite the original.\n` +
@@ -249,6 +372,17 @@ class WikiWrite extends base_command_1.BaseCommand {
                 `it creates. Retitle it with \`${this.config.bin} wiki update ${args.space} ${page.path ?? args.path} ` +
                 `--title ${JSON.stringify(flags.title)}\` (the slug is kept, so stored paths stay valid).`);
         }
+        const ignoredKind = wroteIntoExisting
+            ? kindIgnoredWarning({
+                requested: flags.kind,
+                existingKind: page.kind,
+                binName: this.config.bin,
+                spaceId: args.space,
+                path: page.path ?? args.path,
+            })
+            : null;
+        if (ignoredKind)
+            this.warn(ignoredKind);
         const withUrl = (0, web_url_1.withWikiPageUrl)(this.cliConfig.baseURL, page);
         if (flags.json) {
             this.log(JSON.stringify(withUrl, null, 2));
@@ -260,6 +394,10 @@ class WikiWrite extends base_command_1.BaseCommand {
         let verb = 'Created';
         if (wroteIntoExisting) {
             verb = flags.append ? 'Appended to' : 'Updated';
+            if (flags.lead)
+                verb = 'Replaced the lead of';
+            if (flags.section !== undefined)
+                verb = `Replaced the section ${JSON.stringify(flags.section)} of`;
         }
         this.log(`${verb} ${page.path ?? args.path} (${page.pageId}).`);
         if (withUrl.url)