@gobing-ai/knowledge-kit 0.0.30 → 0.0.32

package/plugins/publishings/substack-pub/package.json

@@ -7,9 +7,11 @@
     },
     "dependencies": {
         "@gobing-ai/kk-core": "workspace:*",
+        "@gobing-ai/ts-browser-automation": "catalog:",
         "@gobing-ai/publish-harness": "workspace:*",
         "@gobing-ai/ts-runtime": "catalog:",
-        "@gobing-ai/ts-utils": "catalog:"
+        "@gobing-ai/ts-utils": "catalog:",
+        "playwright": "catalog:"
     },
     "devDependencies": {
         "@types/bun": "1.3.14"

package/plugins/publishings/substack-pub/plugin.json

@@ -3,5 +3,5 @@
     "kind": "publish",
     "entry": "./dist/index.js",
     "version": "1.0.0",
-    "description": "Publish plugin for Substack via browser/agent transport"
+    "description": "Publish plugin for Substack (substack.com): post drafts through the ProseMirror editor via script browser transport (ts-browser-automation)"
 }

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

@@ -6,63 +6,305 @@ import {
     FakeBrowserTransport,
     type PublishTransport,
     type PublishTransportPayload,
-    resolveBrowserProfileDir,
+    trySelectors,
 } from '@gobing-ai/publish-harness';
+import {
+    type ChannelBrowserConfig,
+    checkChannelSession,
+    expectOutcome,
+    markdownToHtml,
+    pasteHtml,
+    resolveChannelProfileDir,
+    resolveSelector,
+} from '@gobing-ai/publish-harness/browser';
+import {
+    type BrowserLauncher,
+    BrowserProfileMissingError,
+    type IsAuthenticatedPredicate,
+    LoginTimeoutError,
+    withProfilePage,
+} from '@gobing-ai/ts-browser-automation';
 import { createNodeFileSystem } from '@gobing-ai/ts-runtime';
 import { echoError } from '@gobing-ai/ts-utils';
+import type { Page } from 'playwright';
 
-const CHANNEL = 'substack';
+/** Channel slug: names the Result target and resolves the `SUBSTACK_PROFILE_DIR` tier. */
+export const CHANNEL = 'substack';
 const TARGET = 'substack';
+/** Login/account URLs that mean "not authenticated" — the editor never renders behind them. */
+export const LOGIN_URL_RE = /(\/sign-in|substack\.com\/account\/login)/;
+
+/**
+ * Selectors seeded from the wt script (`substack-playwright.ts:84-136`); each list is tried in
+ * order and the operator dogfood (0193) re-measures them. `send` is Substack's
+ * `Send to everyone now` — it emails every subscriber — so both live controls (E91-D5) are
+ * reached only from the `public` branch, after the draft branch has already returned.
+ */
+export const SELECTORS = {
+    title: ['[data-testid="title-input"]', 'textarea[placeholder="Title"]', 'input[placeholder="Title"]'],
+    subtitle: ['[data-testid="subtitle-input"]', 'textarea[placeholder="Add a subtitle..."]'],
+    body: ['.ProseMirror[contenteditable="true"]'],
+    continue: ['[data-testid="continue-button"]', 'button:has-text("Continue")'],
+    send: [
+        '[data-testid="publish-button"]',
+        'button:has-text("Send to everyone now")',
+        'button:has-text("Publish now")',
+    ],
+} as const;
+
+const STEP_TIMEOUT_MS = 30_000;
+const LOGIN_TIMEOUT_MS = 180_000;
+/** Operator recovery command every session failure names — never a cookie, page HTML or stack. */
+const LOGIN_INSTRUCTION = 'bun plugins/publishings/substack-pub/src/profile-check.ts login';
+/** Substack autosaves and rewrites the editor URL onto `/publish/post/<id>`, the whole draft signal. */
+const DRAFT_URL_RE = /\/publish\/post\/(\d+)/;
+/** A live post lands on `/p/<slug>`; the publish queue is `/publish/posts/published`. */
+const LIVE_URL_RE = /\/p\/[^/?#]+|\/publish\/posts\/published/;
+/** Both places the publication URL can come from, named as one thing in every refusal. */
+const PUBLICATION_URL_SOURCES = 'SUBSTACK_PUBLICATION_URL (or --publication <url>)';
+
+/**
+ * The publication's new-post editor: `${base}/publish/post/new`, where the base is the
+ * publication URL without its trailing `/` or `/publish` (seed `substack-playwright.ts:237-244`).
+ */
+export function editorUrl(publicationUrl: string): string {
+    const base = publicationUrl
+        .trim()
+        .replace(/\/$/, '')
+        .replace(/\/publish$/, '');
+    return `${base}/publish/post/new`;
+}
+
+/**
+ * Resolves and validates the run's publication URL (R1, R5): `explicit` — a transport
+ * `options.publicationUrl` or the CLI's `--publication` — wins over `SUBSTACK_PUBLICATION_URL`,
+ * and a blank explicit value stays blank rather than falling through to the environment. Returns
+ * the failure message naming both sources when the tier is unset or is not an `https:` URL, so a
+ * publish run and a profile CLI refuse a bad URL identically, before any browser opens.
+ */
+export function resolvePublicationUrl(explicit?: string): { url: string } | { error: string } {
+    const trimmed = (explicit ?? process.env.SUBSTACK_PUBLICATION_URL)?.trim() ?? '';
+    if (trimmed.length === 0) {
+        return { error: `substack publication URL is required: set ${PUBLICATION_URL_SOURCES}` };
+    }
+    let parsed: URL;
+    try {
+        parsed = new URL(trimmed);
+    } catch {
+        return { error: `substack publication URL is not a URL: '${trimmed}' — set ${PUBLICATION_URL_SOURCES}` };
+    }
+    if (parsed.protocol !== 'https:') {
+        return { error: `substack publication URL must be https:, got '${trimmed}' — set ${PUBLICATION_URL_SOURCES}` };
+    }
+    // Nested editor paths are rejected (residual 0197): `…/publish/posts` used to pass validation
+    // and then be mangled by `editorUrl` (`…/publish/posts/publish/post/new`), so a misconfigured
+    // run reported an expired session instead of a configuration error. A trailing `/publish` is
+    // accepted and stripped by `editorUrl` — that is the documented shape.
+    const trimmedPath = parsed.pathname.replace(/\/+$/, '');
+    if (trimmedPath.length > 0 && trimmedPath !== '/publish') {
+        return {
+            error: `substack publication URL must be the publication root, optionally with a trailing /publish (e.g. https://name.substack.com), got '${trimmed}' — set ${PUBLICATION_URL_SOURCES}`,
+        };
+    }
+    return { url: trimmed };
+}
+
+/**
+ * Substack-owned readiness predicate: the editor is reachable (no login redirect) and the title
+ * field is attached. Shared by the publish preflight and the profile-session CLI (R1, R5).
+ */
+export const isAuthenticated: IsAuthenticatedPredicate = async (page) =>
+    !LOGIN_URL_RE.test(page.url()) && (await trySelectors(page, SELECTORS.title, { visible: false })).found;
+
+/** Site-owned config for the shared session check and operator CLI (0183). */
+export function channelConfig(publicationUrl: string): ChannelBrowserConfig {
+    return {
+        channel: CHANNEL,
+        homeUrl: editorUrl(publicationUrl),
+        isAuthenticated,
+        loginTimeoutMs: LOGIN_TIMEOUT_MS,
+    };
+}
 
 function fail(error: string): Result {
     return ResultSchema.parse({ ok: false, target: TARGET, error });
 }
 
-function draftId(content: Content): string {
-    const title = content.title ?? 'untitled';
-    return `${CHANNEL}-draft-${title.length}`;
+function errorMessage(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
 }
 
-function draftResult(content: Content, driver: BrowserDriver, profileDir: string): Result {
-    return ResultSchema.parse({
-        ok: true,
-        target: TARGET,
-        id: draftId(content),
-        message: `${TARGET} draft prepared (unpublished)`,
-        metadata: { driver, publishStatus: 'draft', profileDir },
-    });
+/** Session failures whose one-liner must name the recovery command (R5). */
+function needsLogin(error: unknown): boolean {
+    return error instanceof LoginTimeoutError || error instanceof BrowserProfileMissingError;
 }
 
 export class SubstackBrowserTransport implements PublishTransport {
     public readonly kind = 'browser';
     public readonly driver: BrowserDriver;
-    private readonly loginTimeoutMs: number;
-    private readonly sessionReady: boolean;
+    private readonly launcher?: BrowserLauncher;
+    private readonly stepTimeoutMs: number;
 
-    constructor(driver: BrowserDriver = 'agent', opts?: { loginTimeoutMs?: number; sessionReady?: boolean }) {
+    constructor(driver: BrowserDriver = 'script', deps: { launcher?: BrowserLauncher; stepTimeoutMs?: number } = {}) {
         this.driver = driver;
-        this.loginTimeoutMs = opts?.loginTimeoutMs ?? 120_000;
-        this.sessionReady = opts?.sessionReady ?? false;
+        this.launcher = deps.launcher;
+        this.stepTimeoutMs = deps.stepTimeoutMs ?? STEP_TIMEOUT_MS;
     }
 
     public async publish(payload: PublishTransportPayload): Promise<Result> {
-        const override =
-            typeof payload.options?.profileDir === 'string'
-                ? payload.options.profileDir
-                : (process.env.SUBSTACK_PROFILE_DIR ?? process.env.KK_BROWSER_PROFILE_DIR);
-        const profileDir = resolveBrowserProfileDir(CHANNEL, override);
-        if (!this.sessionReady) {
-            return fail(
-                `login timeout after ${this.loginTimeoutMs}ms: no authenticated ${CHANNEL} session in ${profileDir}`,
+        if (this.driver !== 'script') {
+            return fail(`unsupported driver '${this.driver}' for ${TARGET}`);
+        }
+        const requested = payload.content.metadata?.publishStatus;
+        if (requested !== undefined && requested !== 'draft' && requested !== 'public') {
+            return fail(`unknown publishStatus '${String(requested)}' (expected absent, 'draft' or 'public')`);
+        }
+        // Pre-validation, before any browser opens: the editor URL is publication-scoped, so an
+        // unset or non-https publication URL has no safe default to fall back to (R1).
+        const requestedUrl =
+            typeof payload.options?.publicationUrl === 'string' ? payload.options.publicationUrl : undefined;
+        const publication = resolvePublicationUrl(requestedUrl);
+        if ('error' in publication) return fail(publication.error);
+
+        const override = typeof payload.options?.profileDir === 'string' ? payload.options.profileDir : undefined;
+        const profileDir = resolveChannelProfileDir(CHANNEL, override);
+
+        // ADR-025 preflight: an unauthenticated or absent profile must never produce a headed
+        // visit, so the read-only headless check runs first and a refusal stays a fast refusal.
+        const session = await checkChannelSession(channelConfig(publication.url), {
+            profileDir,
+            launcher: this.launcher,
+            headedFallback: false,
+            timeoutMs: this.stepTimeoutMs,
+        });
+        if (session.status !== 'verified') {
+            return fail(`${CHANNEL} session preflight refused: ${session.detail} — run: ${LOGIN_INSTRUCTION}`);
+        }
+
+        const publishStatus = requested === 'public' ? 'public' : 'draft';
+        try {
+            return await withProfilePage(
+                {
+                    profileDir,
+                    url: editorUrl(publication.url),
+                    isAuthenticated,
+                    // Headed by default (Substack bot-walls headless loads); the headless preflight
+                    // above is the unattended pass, `options.headless === true` the opt-in.
+                    headless: payload.options?.headless === true,
+                    launcher: this.launcher,
+                    // The session is already preflight-verified, so the post-goto confirmation is
+                    // a bounded step like every other one, not the 180s interactive login wait.
+                    timeoutMs: this.stepTimeoutMs,
+                },
+                async ({ page }) => this.runEditorFlow(page, payload.content, publishStatus, profileDir),
             );
+        } catch (error) {
+            const hint = needsLogin(error) ? ` — run: ${LOGIN_INSTRUCTION}` : '';
+            return fail(`${errorMessage(error)}${hint}`);
+        }
+    }
+
+    /**
+     * The site-owned editor flow: title → optional subtitle → ProseMirror HTML paste → the draft
+     * signal, then — for a live run only — `Continue` → `Send to everyone now` → the live signal.
+     * Substack autosaves the draft, so the draft needs no button click and both outcomes come
+     * from an `expectOutcome` probe (E91-D6): a wait without an observed signal is never a success.
+     */
+    private async runEditorFlow(
+        page: Page,
+        content: Content,
+        publishStatus: 'draft' | 'public',
+        profileDir: string,
+    ): Promise<Result> {
+        const metadata = { driver: this.driver, publishStatus, profileDir };
+
+        const titleSelector = await resolveSelector(page, SELECTORS.title, {
+            timeoutMs: this.stepTimeoutMs,
+            label: 'title input',
+        });
+        await page
+            .locator(titleSelector)
+            .first()
+            .fill(content.title ?? '');
+
+        const subtitle = content.metadata?.subtitle;
+        if (typeof subtitle === 'string' && subtitle.length > 0) {
+            const subtitleSelector = await resolveSelector(page, SELECTORS.subtitle, {
+                timeoutMs: this.stepTimeoutMs,
+                label: 'subtitle input',
+            });
+            await page.locator(subtitleSelector).first().fill(subtitle);
+        }
+
+        const bodySelector = await resolveSelector(page, SELECTORS.body, {
+            timeoutMs: this.stepTimeoutMs,
+            label: 'body editor',
+        });
+        // Substack's editor is ProseMirror rich text: the body goes in as rendered HTML through the
+        // shared paste, never as plain markdown text (E91-D4).
+        await pasteHtml(page, bodySelector, markdownToHtml(content.body), { timeoutMs: this.stepTimeoutMs });
+
+        const draft = await expectOutcome(() => probeDraft(page), {
+            timeoutMs: this.stepTimeoutMs,
+            label: `substack draft signal in '${bodySelector}'`,
+        });
+        if (!draft.ok) return fail(draft.error);
+
+        // The probe only ever returns a `/publish/post/<id>` URL, so this capture always resolves.
+        const id = DRAFT_URL_RE.exec(draft.evidence)?.[1];
+        if (publishStatus === 'draft') {
+            return ResultSchema.parse({
+                ok: true,
+                target: TARGET,
+                ...(id === undefined ? {} : { id }),
+                url: draft.evidence,
+                message: `${TARGET} draft saved (unpublished) in profile ${profileDir}`,
+                metadata,
+            });
         }
-        return draftResult(payload.content, this.driver, profileDir);
+
+        const continueSelector = await resolveSelector(page, SELECTORS.continue, {
+            timeoutMs: this.stepTimeoutMs,
+            label: 'continue control',
+        });
+        await page.locator(continueSelector).first().click();
+        const sendSelector = await resolveSelector(page, SELECTORS.send, {
+            timeoutMs: this.stepTimeoutMs,
+            label: 'send control',
+        });
+        await page.locator(sendSelector).first().click();
+        const live = await expectOutcome(() => probeLive(page), {
+            timeoutMs: this.stepTimeoutMs,
+            label: `substack publish '${sendSelector}'`,
+        });
+        if (!live.ok) return fail(live.error);
+
+        return ResultSchema.parse({
+            ok: true,
+            target: TARGET,
+            ...(id === undefined ? {} : { id }),
+            url: live.evidence,
+            message: `${TARGET} published live in profile ${profileDir}`,
+            metadata,
+        });
     }
 }
 
-export function getPublishTransport(driver: BrowserDriver = 'agent'): PublishTransport {
+/** Draft evidence is URL-only by design: Substack's autosave rewrites `/publish/post/new`. */
+async function probeDraft(page: Page): Promise<string | null> {
+    const url = page.url();
+    return DRAFT_URL_RE.test(url) ? url : null;
+}
+
+/** Live evidence is URL-only too: `/p/<slug>` (the published post) or the publish queue. */
+async function probeLive(page: Page): Promise<string | null> {
+    const url = page.url();
+    return LIVE_URL_RE.test(url) ? url : null;
+}
+
+export function getPublishTransport(driver: BrowserDriver = 'script'): PublishTransport {
     if (process.env.KNOWLEDGE_KIT_PUBLISH_TRANSPORT === 'fake') {
-        return new FakeBrowserTransport(driver);
+        return new FakeBrowserTransport('script');
     }
     return new SubstackBrowserTransport(driver);
 }

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

@@ -0,0 +1,74 @@
+/**
+ * Substack profile-session capability (R5, AC3).
+ *
+ * `login` opens the publication's editor in a headed browser and resolves only once Substack's
+ * readiness predicate passes; `check` reopens the profile headlessly and reports `verified` or
+ * `refused`. Arg parsing, profile precedence (`--profile` > `SUBSTACK_PROFILE_DIR` >
+ * `KK_BROWSER_PROFILE_DIR` > `~/.config/kk/browser-profiles/substack`) and the exit codes
+ * (0 verified, 1 refused, 2 usage error) all live in the shared `runProfileCli` (0183), so the
+ * publish preflight and this CLI apply the same gate.
+ *
+ * The publication is publication-scoped, so it comes from `--publication <url>` or
+ * `SUBSTACK_PUBLICATION_URL`; `--publication` is stripped before `runProfileCli` parses the rest
+ * (the shared CLI rejects a flag it does not know), and a missing or non-https value is a usage
+ * error that opens no browser.
+ *
+ * Operator dogfood (plan step 6, handed to 0193): run `profile-check.ts login`, then `check`, on
+ * the same profile, and re-measure the editor URL, the selectors and the draft signal.
+ */
+import { type ChannelBrowserConfig, type ProfileCliDeps, runProfileCli } from '@gobing-ai/publish-harness/browser';
+import { echo } from '@gobing-ai/ts-utils';
+import { channelConfig, resolvePublicationUrl } from './index';
+
+const PUBLICATION_FLAG = '--publication';
+const USAGE = 'usage: substack profile-check [login|check] [--publication <url>] [--profile <dir>] [--timeout <ms>]';
+
+/**
+ * Splits `--publication <url>` / `--publication=<url>` out of the operator argv; `rest` keeps the
+ * `login|check` positional and the `--profile` / `--timeout` flags `runProfileCli` owns. A flag
+ * with no value stays an empty string, so it is refused as a blank publication URL instead of
+ * silently falling through to the environment.
+ */
+export function splitPublicationFlag(argv: readonly string[]): { publicationUrl?: string; rest: string[] } {
+    const rest: string[] = [];
+    let publicationUrl: string | undefined;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index] ?? '';
+        if (arg === PUBLICATION_FLAG) {
+            publicationUrl = argv[index + 1] ?? '';
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith(`${PUBLICATION_FLAG}=`)) {
+            publicationUrl = arg.slice(PUBLICATION_FLAG.length + 1);
+            continue;
+        }
+        rest.push(arg);
+    }
+    return { publicationUrl, rest };
+}
+
+/**
+ * `login|check` for one publication: the shared CLI over `channelConfig(publicationUrl)`.
+ * Exit codes: 0 verified (or logged in), 1 refused, 2 usage error — the publication URL is
+ * resolved (and refused) before anything launches.
+ */
+export async function main(argv: readonly string[] = Bun.argv.slice(2), deps: ProfileCliDeps = {}): Promise<number> {
+    const stdout =
+        deps.stdout ??
+        ((line: string) => {
+            echo(line);
+        });
+    const { publicationUrl, rest } = splitPublicationFlag(argv);
+    const publication = resolvePublicationUrl(publicationUrl);
+    if ('error' in publication) {
+        stdout(`substack profile-check: ${publication.error} — ${USAGE}`);
+        return 2;
+    }
+    const config: ChannelBrowserConfig = channelConfig(publication.url);
+    return runProfileCli(config, [...rest], { ...deps, stdout });
+}
+
+if (import.meta.main) {
+    process.exit(await main());
+}

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

@@ -14665,7 +14665,7 @@ var init_zod = __esm(() => {
   init_external();
 });
 
-// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.11/node_modules/@gobing-ai/ts-utils/dist/errors.js
+// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.15/node_modules/@gobing-ai/ts-utils/dist/errors.js
 var ErrorCode;
 var init_errors3 = __esm(() => {
   ErrorCode = {
@@ -14676,7 +14676,7 @@ var init_errors3 = __esm(() => {
   };
 });
 
-// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.11/node_modules/@gobing-ai/ts-utils/dist/api-response.js
+// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.15/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();
@@ -14699,13 +14699,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.11/node_modules/@gobing-ai/ts-utils/dist/cursor.js
+// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.15/node_modules/@gobing-ai/ts-utils/dist/cursor.js
 var init_cursor = () => {};
 
-// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.11/node_modules/@gobing-ai/ts-utils/dist/event-severity.js
+// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.15/node_modules/@gobing-ai/ts-utils/dist/event-severity.js
 var init_event_severity = () => {};
 
-// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.11/node_modules/@gobing-ai/ts-utils/dist/output.js
+// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.15/node_modules/@gobing-ai/ts-utils/dist/output.js
 function processStream(name) {
   const proc = globalThis.process;
   const stream = proc?.[name];
@@ -14723,7 +14723,7 @@ function echoError(message, target = defaultStderrTarget ?? processStream("stder
 }
 var defaultStderrTarget;
 
-// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.11/node_modules/@gobing-ai/ts-utils/dist/index.js
+// ../../node_modules/.bun/@gobing-ai+ts-utils@0.5.15/node_modules/@gobing-ai/ts-utils/dist/index.js
 var init_dist = __esm(() => {
   init_api_response();
   init_cursor();
@@ -21721,7 +21721,7 @@ var init_dist2 = __esm(() => {
   $visitAsync = visit.visitAsync;
 });
 
-// ../../node_modules/.bun/@gobing-ai+ts-runtime@0.5.11/node_modules/@gobing-ai/ts-runtime/dist/config.js
+// ../../node_modules/.bun/@gobing-ai+ts-runtime@0.5.15/node_modules/@gobing-ai/ts-runtime/dist/config.js
 var configSchema;
 var init_config = __esm(() => {
   init_dist2();
@@ -21745,7 +21745,7 @@ var init_config = __esm(() => {
   });
 });
 
-// ../../node_modules/.bun/@gobing-ai+ts-runtime@0.5.11/node_modules/@gobing-ai/ts-runtime/dist/file-system-node.js
+// ../../node_modules/.bun/@gobing-ai+ts-runtime@0.5.15/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) {
@@ -22041,7 +22041,7 @@ var PluginManifestSchema = exports_external.looseObject({
   description: exports_external.string().optional(),
   operations: exports_external.record(exports_external.string(), PluginOperationSchema).optional()
 });
-// ../../node_modules/.bun/@gobing-ai+ts-runtime@0.5.11/node_modules/@gobing-ai/ts-runtime/dist/index.js
+// ../../node_modules/.bun/@gobing-ai+ts-runtime@0.5.15/node_modules/@gobing-ai/ts-runtime/dist/index.js
 init_file_system_node();
 init_config();