@gobing-ai/knowledge-kit 0.0.32 → 0.0.34

package/plugins/publishings/xhs-pub/src/index.ts

@@ -10,10 +10,11 @@ import {
 import {
     checkChannelSession,
     createShadowFinder,
+    kkBrowserLauncher,
     resolveChannelProfileDir,
     type ShadowCdpSession,
 } from '@gobing-ai/publish-harness/browser';
-import { type BrowserLauncher, openPersistentBrowser } from '@gobing-ai/ts-browser-automation';
+import type { BrowserLauncher } from '@gobing-ai/ts-browser-automation';
 import { createNodeFileSystem } from '@gobing-ai/ts-runtime';
 import { echoError } from '@gobing-ai/ts-utils';
 import { type AutomationGuard, createAutomationGuard } from './automation-guard';
@@ -72,6 +73,71 @@ function fail(error: string): Result {
     return ResultSchema.parse({ ok: false, target: TARGET, error });
 }
 
+/** One operation of a visit: its own Content and the mode input validated before any browser work. */
+interface VisitOperation {
+    content: Content;
+    input: ModeInput;
+}
+
+/**
+ * A follow-up operation of a visit: planned, or refused with the reason it never reached the console.
+ * A refused follow-up is reported as its own failed Result entry — it can never fail the note the
+ * visit was opened for (ADR-025 amendment 2026-10-09).
+ */
+type VisitFollowUp = { content: Content; operation: string; input: ModeInput } | { operation: string; error: string };
+
+interface VisitPlan {
+    /** The requested operation, resolved and validated exactly as before task 0236. */
+    primary: VisitOperation;
+    /** The primary Content's `metadata.followUps`, in declared order. */
+    followUps: VisitFollowUp[];
+}
+
+/**
+ * Plan a visit (ADR-025 amendment 2026-10-09, task 0236 option A): the requested operation plus the
+ * follow-ups the caller attached to the primary Content's `metadata.followUps`. One headed visit may
+ * compose several notes under ONE cap entry — the cap still counts visits, not notes.
+ *
+ * The primary is planned as it always was: an unplannable primary is a `fail` and no browser opens.
+ * A follow-up that cannot be planned (not a Content, an undeclared operation, a missing or unreadable
+ * artifact) is refused here, before any console work, and reported as its own entry instead. A
+ * `metadata.followUps` that is not an array is a caller error, so it fails loud before any browser.
+ */
+async function planVisit(
+    primary: VisitOperation,
+    content: Content,
+): Promise<{ plan: VisitPlan; error?: undefined } | { plan?: undefined; error: string }> {
+    const raw = content.metadata?.followUps;
+    if (raw === undefined) return { plan: { primary, followUps: [] } };
+    if (!Array.isArray(raw)) {
+        return {
+            error: `followUps validation: Content.metadata.followUps must be an array of Content objects, got ${typeof raw}`,
+        };
+    }
+    const followUps: VisitFollowUp[] = [];
+    for (const [index, entry] of raw.entries()) {
+        const label = `followUps[${index}]`;
+        const parsed = ContentSchema.safeParse(entry);
+        if (!parsed.success) {
+            followUps.push({ operation: label, error: `${label} is not a Content object` });
+            continue;
+        }
+        const operation = typeof parsed.data.metadata?.operation === 'string' ? parsed.data.metadata.operation : label;
+        const requested = resolveXhsOperation(undefined, parsed.data);
+        if (requested.error !== undefined) {
+            followUps.push({ operation, error: requested.error });
+            continue;
+        }
+        const validation = await validateModeInput(requested.operation, parsed.data);
+        if (validation.error !== undefined) {
+            followUps.push({ operation, error: validation.error });
+            continue;
+        }
+        followUps.push({ content: parsed.data, operation: requested.operation, input: validation.input });
+    }
+    return { plan: { primary, followUps } };
+}
+
 /** CDP is Chromium-only; when unavailable the submit step fails loud instead of guessing. */
 export async function createShadowProbe(
     context: { newCDPSession?(page: unknown): Promise<ShadowCdpSession> },
@@ -93,15 +159,15 @@ export async function isXhsConsoleReady(page: XhsPage): Promise<boolean> {
 }
 
 /**
- * Production launcher: the upstream typed persistent-context opener (0177). Named so the
+ * Production launcher: the harness kk launcher (0214; full-Chromium channel + stealth). Named so the
  * migration is provable offline — tests assert this binding, never launch a real browser.
  */
-export const defaultLauncher = openPersistentBrowser;
+export const defaultLauncher = kkBrowserLauncher.launch;
 
 /**
  * Build the default page opener. The launcher is injected so the seam (page wrapping, shadow
  * probe wiring, context close, launch-failure message) is testable without launching a browser;
- * production uses the upstream typed `openPersistentBrowser` (@gobing-ai/ts-browser-automation).
+ * production uses the harness `kkBrowserLauncher` (@gobing-ai/publish-harness/browser, 0214).
  */
 export function makeDefaultOpenPage(
     launch: (options: { profileDir: string; headless: boolean }) => Promise<unknown> = defaultLauncher,
@@ -147,6 +213,8 @@ export interface SessionCheckOptions {
     profileDir: string;
     timeoutMs?: number;
     launcher?: BrowserLauncher;
+    /** 0216: skip the headless pass and probe headed only (manual `check --headed`). */
+    headedOnly?: boolean;
 }
 
 /**
@@ -173,6 +241,7 @@ export async function checkXhsProfileSession(opts: SessionCheckOptions): Promise
             profileDir: opts.profileDir,
             launcher: opts.launcher,
             timeoutMs: opts.timeoutMs ?? PREFLIGHT_TIMEOUT_MS,
+            headedOnly: opts.headedOnly === true,
         },
     );
 }
@@ -235,13 +304,20 @@ export class XhsBrowserTransport implements PublishTransport {
         if (validation.error !== undefined) return fail(validation.error);
         const input: ModeInput = validation.input;
 
+        // ADR-025 amendment (2026-10-09, task 0236 option A): one visit may compose more than one
+        // note. The follow-ups ride the primary Content's `metadata.followUps` and are planned here,
+        // with the primary, before any browser work.
+        const visited = await planVisit({ content: payload.content, input }, payload.content);
+        if (visited.error !== undefined) return fail(visited.error);
+        const visit = visited.plan;
+
         const override = typeof payload.options?.profileDir === 'string' ? payload.options.profileDir : undefined;
         const profileDir = resolveChannelProfileDir(CHANNEL, override);
-        const publishStatus = payload.content.metadata?.publishStatus === 'public' ? 'public' : 'draft';
 
         // ADR-025 automation guard — both gates run before any browser opens.
         // 1. Frequency cap: the operator's platform warning makes a repeated console visit an
-        //    account-level risk, not merely a failed run.
+        //    account-level risk, not merely a failed run. The cap counts VISITS: one allow/record
+        //    per visit covers every note the visit composes.
         const cap = this.automation.allow('publish');
         if (!cap.allowed) return fail(`automation cap: ${cap.reason}`);
         // 2. Headless session preflight: an unauthenticated profile must never produce a headed
@@ -262,6 +338,41 @@ export class XhsBrowserTransport implements PublishTransport {
             return fail(error instanceof Error ? error.message : String(error));
         }
         const { page, close } = opened;
+        try {
+            // The visit's own Result is the primary operation's: a failed primary ends the visit, as
+            // it always did, and only a primary that stood reports its follow-ups.
+            const primary = await this.runStep(visit.primary.input, visit.primary.content, page, profileDir);
+            if (!primary.ok || visit.followUps.length === 0) return primary;
+            // One Result entry per operation, in declared order; a refused and a failed follow-up
+            // are the same kind of entry, and neither can fail the note the visit was opened for.
+            const followUps: Result[] = [];
+            for (const followUp of visit.followUps) {
+                const step =
+                    'error' in followUp
+                        ? fail(`follow-up (${followUp.operation}): ${followUp.error}`)
+                        : await this.runStep(followUp.input, followUp.content, page, profileDir);
+                // Every entry names the operation it was planned under — a failed or refused one too,
+                // so the caller can tell which note fell; the step's own metadata wins.
+                followUps.push(
+                    ResultSchema.parse({ ...step, metadata: { operation: followUp.operation, ...step.metadata } }),
+                );
+            }
+            return ResultSchema.parse({ ...primary, metadata: { ...primary.metadata, followUps } });
+        } finally {
+            await close();
+        }
+    }
+
+    /**
+     * Run one operation of the visit in the page the visit already opened. Every step enters the
+     * console from its landing view: the primary needs the login gate and the pre-entry draft
+     * baseline, and a follow-up needs both again — the previous note's editor replaces the header,
+     * and the baseline must be read before THIS note's mode is entered.
+     *
+     * A step never throws: its failure is that operation's own `ok:false` Result, which is what keeps
+     * a failed follow-up from failing the visit (ADR-025 amendment 2026-10-09).
+     */
+    private async runStep(input: ModeInput, content: Content, page: XhsPage, profileDir: string): Promise<Result> {
         const act = async <T>(what: string, fn: () => Promise<T>): Promise<T> => {
             try {
                 return await fn();
@@ -279,6 +390,7 @@ export class XhsBrowserTransport implements PublishTransport {
                 );
             }
 
+            const publishStatus = content.metadata?.publishStatus === 'public' ? 'public' : 'draft';
             // The draft counter and any save timestamps exist only on the landing view, so the
             // baseline is captured before the mode is entered (the editor replaces the header).
             const draftBaseline =
@@ -286,7 +398,7 @@ export class XhsBrowserTransport implements PublishTransport {
 
             return await runMode(input, {
                 page,
-                content: payload.content,
+                content,
                 publishStatus,
                 profileDir,
                 driver: this.driver,
@@ -297,8 +409,6 @@ export class XhsBrowserTransport implements PublishTransport {
             });
         } catch (error) {
             return fail(error instanceof Error ? error.message : String(error));
-        } finally {
-            await close();
         }
     }
 }

package/plugins/publishings/xhs-pub/src/page.ts

@@ -1,4 +1,5 @@
 import { trySelectors } from '@gobing-ai/publish-harness';
+import { waitUntil } from '@gobing-ai/publish-harness/browser';
 
 /**
  * The console's page seam (ADR-029) and the helpers every xhs operation shares.
@@ -10,6 +11,9 @@ import { trySelectors } from '@gobing-ai/publish-harness';
  */
 
 export const POLL_MS = 500;
+
+// The shared poll (0184 R2); re-exported so flow/index keep importing it from here.
+export { waitUntil };
 export const STEP_TIMEOUT_MS = 30_000;
 
 /** The console's mode tab bar; it mounts late and renders every tab several times over. */
@@ -120,23 +124,6 @@ export async function clickCreatorTab(
     }
 }
 
-/**
- * Poll `predicate` every `pollMs` until the deadline, then evaluate it one final time. The trailing
- * call matters: the condition often becomes true exactly at the boundary.
- */
-export async function waitUntil(
-    predicate: () => Promise<boolean>,
-    timeoutMs: number,
-    pollMs = POLL_MS,
-): Promise<boolean> {
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-        if (await predicate()) return true;
-        await new Promise((resolve) => setTimeout(resolve, pollMs));
-    }
-    return predicate();
-}
-
 export function wrapPlaywrightPage(raw: unknown, shadow?: ShadowProbe): XhsPage {
     const pw = raw as {
         goto(url: string, options?: Record<string, unknown>): Promise<unknown>;

package/plugins/publishings/xhs-pub/src/profile-check.ts

@@ -6,7 +6,8 @@
  *  - `login` recovers an absent/expired session headed via the upstream
  *    `loginWithProfile`, polled with the same XHS-owned readiness gate the publish
  *    flow uses;
- *  - `check` reopens the existing profile headless and reports the session as
+ *  - `check` reopens the existing profile (headless by default; `--headed` skips the headless
+ *    pass and probes headed only, 0216) and reports the session as
  *    `verified` or `refused` — a site refusal, expired session, or missing profile
  *    is an explicit failed readiness, never a success. The upstream launcher never
  *    creates a profile headless, so a check cannot fabricate a session from a
@@ -21,7 +22,7 @@
  * the full recipe lives in docs/design/xhs-image-cards.md.
  */
 import { parseArgs } from 'node:util';
-import { resolveChannelProfileDir } from '@gobing-ai/publish-harness/browser';
+import { kkBrowserLauncher, resolveChannelProfileDir } from '@gobing-ai/publish-harness/browser';
 import { type BrowserLauncher, loginWithProfile } from '@gobing-ai/ts-browser-automation';
 import { echo, echoError } from '@gobing-ai/ts-utils';
 import { type AutomationGuard, createAutomationGuard } from './automation-guard';
@@ -60,11 +61,20 @@ export async function loginProfile(opts: ProfileLoginOptions): Promise<void> {
         url: PUBLISH_URL,
         isAuthenticated: (page) => isXhsConsoleReady(wrapPlaywrightPage(page)),
         timeoutMs: opts.timeoutMs ?? LOGIN_TIMEOUT_MS,
-        launcher: opts.launcher,
+        launcher: opts.launcher ?? kkBrowserLauncher,
     });
 }
 
-/** `login|check [--profile <dir>] [--timeout <ms>]`; profile precedence matches the publish flow. */
+/** Exit 2 with the human usage on stderr and the ADR-032 `error` verdict as the last stdout line. */
+function usageError(message: string): number {
+    echoError(
+        `profile-check: ${message} — usage: profile-check.ts [login|check] [--profile <dir>] [--timeout <ms>] [--headed]`,
+    );
+    echo(JSON.stringify({ status: 'error', detail: message }));
+    return 2;
+}
+
+/** `login|check [--profile <dir>] [--timeout <ms>] [--headed]`; profile precedence matches the publish flow. */
 export async function main(
     argv: string[] = process.argv.slice(2),
     launcher?: BrowserLauncher,
@@ -73,13 +83,19 @@ export async function main(
     let command: string;
     let profileDir: string;
     let timeoutMs: number | undefined;
+    let headed = false;
     try {
         const { positionals, values } = parseArgs({
             args: argv,
             allowPositionals: true,
-            options: { profile: { type: 'string' }, timeout: { type: 'string' } },
+            options: {
+                profile: { type: 'string' },
+                timeout: { type: 'string' },
+                headed: { type: 'boolean' },
+            },
         });
         command = positionals[0] ?? 'check';
+        headed = values.headed === true;
         if (values.timeout !== undefined) {
             timeoutMs = Number(values.timeout);
             if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
@@ -88,10 +104,7 @@ export async function main(
         }
         profileDir = resolveChannelProfileDir(CHANNEL, values.profile);
     } catch (error) {
-        echoError(
-            `profile-check: ${error instanceof Error ? error.message : String(error)} — usage: profile-check.ts [login|check] [--profile <dir>] [--timeout <ms>]`,
-        );
-        return 1;
+        return usageError(error instanceof Error ? error.message : String(error));
     }
     if (command === 'login') {
         try {
@@ -104,21 +117,21 @@ export async function main(
         }
     }
     if (command !== 'check') {
-        echoError(
-            `profile-check: unknown command '${command}' — usage: profile-check.ts [login|check] [--profile <dir>] [--timeout <ms>]`,
-        );
-        return 1;
+        return usageError(`unknown command '${command}'`);
     }
     // ADR-025: a manual session check is a real console visit, so it draws on the shared 2h
     // automation budget rather than a separate one. `login` is deliberately uncapped above: it is
     // operator-interactive, so capping it would only block recovery from an expired session.
     const cap = guard.allow('check');
     if (!cap.allowed) {
-        echoError(`profile-check: ${cap.reason}`);
+        // The budget refusal is still a readiness verdict (0216 contract): emit the JSON line so
+        // `kk plugin check` reports a refusal with the operator hint instead of a malformed probe.
+        echo(JSON.stringify({ status: 'refused', profileDir, detail: `xhs readiness refused: ${cap.reason}` }));
+        echoError(cap.reason);
         return 1;
     }
     guard.record('check');
-    const outcome = await checkXhsProfileSession({ profileDir, timeoutMs, launcher });
+    const outcome = await checkXhsProfileSession({ profileDir, timeoutMs, launcher, headedOnly: headed });
     echo(JSON.stringify(outcome));
     if (outcome.status !== 'verified') {
         echoError(outcome.detail);

package/plugins/publishings/zenn-pub/dist/index.js

@@ -14642,7 +14642,7 @@ var init_zod = __esm(() => {
   init_external();
 });
 
-// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.15/node_modules/@gobing-ai/ts-utils/dist/errors.js
+// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.21/node_modules/@gobing-ai/ts-utils/dist/errors.js
 var ErrorCode;
 var init_errors3 = __esm(() => {
   ErrorCode = {
@@ -14653,7 +14653,7 @@ var init_errors3 = __esm(() => {
   };
 });
 
-// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.15/node_modules/@gobing-ai/ts-utils/dist/api-response.js
+// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.21/node_modules/@gobing-ai/ts-utils/dist/api-response.js
 var API_ERROR_CODES, ERROR_CODE_TO_HTTP, CLIENT_SAFE_CODES;
 var init_api_response = __esm(() => {
   init_errors3();
@@ -14676,13 +14676,13 @@ var init_api_response = __esm(() => {
   CLIENT_SAFE_CODES = new Set([ErrorCode.NotFound, ErrorCode.Validation, ErrorCode.Conflict]);
 });
 
-// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.15/node_modules/@gobing-ai/ts-utils/dist/cursor.js
+// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.21/node_modules/@gobing-ai/ts-utils/dist/cursor.js
 var init_cursor = () => {};
 
-// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.15/node_modules/@gobing-ai/ts-utils/dist/event-severity.js
+// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.21/node_modules/@gobing-ai/ts-utils/dist/event-severity.js
 var init_event_severity = () => {};
 
-// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.15/node_modules/@gobing-ai/ts-utils/dist/output.js
+// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.21/node_modules/@gobing-ai/ts-utils/dist/output.js
 function processStream(name) {
   const proc = globalThis.process;
   const stream = proc?.[name];
@@ -14700,7 +14700,7 @@ function echoError(message, target = defaultStderrTarget ?? processStream("stder
 }
 var defaultStderrTarget;
 
-// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.15/node_modules/@gobing-ai/ts-utils/dist/index.js
+// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.21/node_modules/@gobing-ai/ts-utils/dist/index.js
 var init_dist = __esm(() => {
   init_api_response();
   init_cursor();
@@ -21698,7 +21698,7 @@ var init_dist2 = __esm(() => {
   $visitAsync = visit.visitAsync;
 });
 
-// ../../node_modules/.bun/@gobing-ai+ts-runtime@0.5.15/node_modules/@gobing-ai/ts-runtime/dist/config.js
+// ../../node_modules/.bun/@gobing-ai+ts-runtime@0.5.21+44edd5c4d6372504/node_modules/@gobing-ai/ts-runtime/dist/config.js
 var configSchema;
 var init_config = __esm(() => {
   init_dist2();
@@ -21722,7 +21722,7 @@ var init_config = __esm(() => {
   });
 });
 
-// ../../node_modules/.bun/@gobing-ai+ts-runtime@0.5.15/node_modules/@gobing-ai/ts-runtime/dist/file-system-node.js
+// ../../node_modules/.bun/@gobing-ai+ts-runtime@0.5.21+44edd5c4d6372504/node_modules/@gobing-ai/ts-runtime/dist/file-system-node.js
 import { appendFileSync, cpSync, createReadStream, createWriteStream, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "fs";
 import { dirname, resolve as resolvePath } from "path";
 function createNodeFileSystem(root, paths) {
@@ -21897,11 +21897,12 @@ var PluginManifestSchema = exports_external.looseObject({
   name: exports_external.string().min(1),
   kind: PluginKindSchema,
   entry: exports_external.string().min(1),
+  check: exports_external.string().min(1).optional(),
   version: exports_external.string().optional(),
   description: exports_external.string().optional(),
   operations: exports_external.record(exports_external.string(), PluginOperationSchema).optional()
 });
-// ../../node_modules/.bun/@gobing-ai+ts-runtime@0.5.15/node_modules/@gobing-ai/ts-runtime/dist/index.js
+// ../../node_modules/.bun/@gobing-ai+ts-runtime@0.5.21+44edd5c4d6372504/node_modules/@gobing-ai/ts-runtime/dist/index.js
 init_file_system_node();
 init_config();