@gobing-ai/knowledge-kit 0.0.36 → 0.1.0

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

@@ -0,0 +1,172 @@
+/**
+ * cnblogs-pub — cnblogs (www.cnblogs.com) Markdown-article publisher plugin surface (task 0293).
+ *
+ * This module is the manifest-facing plugin surface: the declared operation list, the pre-browser
+ * refusal ladder (operation → driver → publishStatus → payload → unsupported fields → category
+ * types → local Markdown images — all refused before any browser opens), `getPublishTransport`,
+ * the `--in/--out` IO contract and the CLI `main`. The selectors live in `src/selectors.ts`, the
+ * browser transport and flow in `src/flow.ts`, and the operator session CLI in
+ * `src/profile-check.ts`.
+ *
+ * Evidence: the recovered extension adapter
+ * `.spur/memory/evidence/publish-ready-0288-0297-20261014-01/source/platforms/cnblogs.js` pins the
+ * field semantics cited below (fill cnblogs.js:20-32, register map cnblogs.js:35-37) but is a
+ * fill-only adapter — no save/publish protocol, no receipt. Its upload.cnblogs.com XSRF image
+ * endpoint (cnblogs.js:5-18) and its replace-with-uploaded-URL image pass (cnblogs.js:24) are
+ * deliberately NOT ported: requested cover/tags/images refuse, non-HTTPS Markdown image refs
+ * refuse before submit without echoing the path, and existing HTTPS image URLs stay literal.
+ *
+ * publishStatus contract (task 0293 Design freeze): absent defaults to 'draft', 'draft' saves
+ * through the exact-visible 保存草稿|存为草稿 control, 'public' activates 发布|发布博文 — both
+ * provisional, bounded, fail closed — and any other value refuses before the browser.
+ */
+import { dirname } from 'node:path';
+import { parseArgs } from 'node:util';
+import { type Content, ContentSchema, type Result, ResultSchema } from '@gobing-ai/kk-core';
+import { type BrowserDriver, FakeBrowserTransport, type PublishTransport } from '@gobing-ai/publish-harness';
+import { createNodeFileSystem } from '@gobing-ai/ts-runtime';
+import { echoError } from '@gobing-ai/ts-utils';
+import { bounded, boundedDetail, CnblogsBrowserTransport, countNonHttpsImageRefs, errorMessage, fail } from './flow';
+import { CNBLOGS_TARGET } from './selectors';
+
+/** Declared operations (ADR-029 dispatch): the source handles article only (cnblogs.js:21). */
+export const CNBLOGS_OPERATIONS = ['article'] as const;
+export type CnblogsOperation = (typeof CNBLOGS_OPERATIONS)[number];
+
+/**
+ * Resolves the requested operation. An undeclared value is refused by name, before any transport —
+ * and therefore before any browser — is resolved (the source handles article only, cnblogs.js:21).
+ * @param options - Per-call publish options (`operation`).
+ * @param content - Content whose `metadata.operation` is the fallback source.
+ * @returns The resolved operation, or the refusal message.
+ */
+export function resolveOperation(
+    options?: Record<string, unknown>,
+    content?: Content,
+): { operation: CnblogsOperation; error?: undefined } | { operation?: undefined; error: string } {
+    const raw = options?.operation ?? content?.metadata?.operation ?? 'article';
+    if (typeof raw !== 'string' || !(CNBLOGS_OPERATIONS as readonly string[]).includes(raw)) {
+        return {
+            error: `unsupported operation '${bounded(raw)}' for ${CNBLOGS_TARGET}: expected one of ${CNBLOGS_OPERATIONS.join(', ')}`,
+        };
+    }
+    return { operation: raw as CnblogsOperation };
+}
+
+/**
+ * Resolves the driver from `options.driver ?? 'script'`. This channel ships one driver and no
+ * `agent` path, so anything else — including a wrong type — is refused by name before a transport
+ * is built.
+ * @param options - Per-call publish options (`driver`).
+ * @returns The resolved driver, or the refusal message.
+ */
+function resolveDriver(
+    options?: Record<string, unknown>,
+): { driver: BrowserDriver; error?: undefined } | { driver?: undefined; error: string } {
+    const raw = options?.driver ?? 'script';
+    if (raw !== 'script') {
+        return {
+            error: `unsupported driver '${bounded(raw)}' for ${CNBLOGS_TARGET}: expected one of script (the cnblogs-pub browser flow has no agent path)`,
+        };
+    }
+    return { driver: 'script' };
+}
+
+/**
+ * Resolves the channel transport: the publish-harness fake under
+ * `KNOWLEDGE_KIT_PUBLISH_TRANSPORT=fake` (offline, no profile, no browser), otherwise the real
+ * cnblogs browser transport (`src/flow.ts`).
+ * @param operation - Resolved operation (`article`).
+ * @param driver - Resolved driver; only `script` is declared.
+ * @returns The publish transport for this channel.
+ */
+export function getPublishTransport(
+    operation: CnblogsOperation = 'article',
+    driver: BrowserDriver = 'script',
+): PublishTransport {
+    if (process.env.KNOWLEDGE_KIT_PUBLISH_TRANSPORT === 'fake') return new FakeBrowserTransport('script');
+    return new CnblogsBrowserTransport(operation, driver);
+}
+
+/** Writes the Result to `--out`, creating its directory when the caller named a nested path. */
+async function writePublishResult(outputPath: string, result: Result): Promise<void> {
+    const outDir = dirname(outputPath);
+    if (outDir && outDir !== '.') await createNodeFileSystem().ensureDir(outDir);
+    await createNodeFileSystem().writeFile(outputPath, JSON.stringify(result, null, 2));
+}
+
+/**
+ * The plugin's `--in/--out` contract: validate the Content, resolve **and refuse** the operation
+ * and the driver before any transport exists, then publish through the injected or configured
+ * transport (whose own ladder refuses status/payload/unsupported-field/category/image problems —
+ * also all pre-browser).
+ * @param inputPath - Path to the Content JSON.
+ * @param outputPath - Path the Result JSON is written to, on success and on refusal.
+ * @param transport - Optional transport injection for tests and offline runs.
+ */
+export async function processPublishIO(
+    inputPath: string,
+    outputPath: string,
+    transport?: PublishTransport,
+): Promise<void> {
+    await createNodeFileSystem().deleteFile(outputPath);
+    let content: Content;
+    let options: Record<string, unknown> | undefined;
+    try {
+        const raw = JSON.parse(await createNodeFileSystem().readFile(inputPath)) as Record<string, unknown>;
+        content = ContentSchema.parse(raw);
+        if (raw.options !== undefined && typeof raw.options === 'object' && raw.options !== null) {
+            options = raw.options as Record<string, unknown>;
+        }
+    } catch (error: unknown) {
+        const message = boundedDetail(`Invalid Content input: ${errorMessage(error)}`);
+        await writePublishResult(outputPath, fail(CNBLOGS_TARGET, message));
+        throw new Error(message);
+    }
+    const mode = resolveOperation(options, content);
+    if (mode.error !== undefined) {
+        await writePublishResult(outputPath, fail(CNBLOGS_TARGET, mode.error));
+        throw new Error(mode.error);
+    }
+    const driverMode = resolveDriver(options);
+    if (driverMode.error !== undefined) {
+        await writePublishResult(outputPath, fail(CNBLOGS_TARGET, driverMode.error));
+        throw new Error(driverMode.error);
+    }
+    const resolved = transport ?? getPublishTransport(mode.operation, driverMode.driver);
+    const result = ResultSchema.parse(await resolved.publish({ content, options }));
+    await writePublishResult(outputPath, result);
+    if (!result.ok) throw new Error(result.error ?? 'Publish failed');
+}
+
+/**
+ * CLI entry point: `--in <content.json> --out <result.json>`.
+ * @returns Process exit code (0 published, 1 refused or invalid arguments).
+ */
+export async function main(): Promise<number> {
+    let values: { in?: string; out?: string };
+    try {
+        ({ values } = parseArgs({ options: { in: { type: 'string' }, out: { type: 'string' } } }));
+    } catch (error: unknown) {
+        echoError(`Invalid arguments: ${errorMessage(error)}`);
+        return 1;
+    }
+    if (!values.in || !values.out) {
+        echoError('Missing required arguments: --in and --out');
+        return 1;
+    }
+    try {
+        await processPublishIO(values.in, values.out);
+        return 0;
+    } catch (error: unknown) {
+        echoError(`cnblogs-pub failed: ${boundedDetail(errorMessage(error))}`);
+        return 1;
+    }
+}
+
+if (import.meta.main) {
+    process.exit(await main());
+}
+
+/** Re-exported so the local Markdown-image rule stays observable from the plugin surface. */
+export { countNonHttpsImageRefs };

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

@@ -0,0 +1,24 @@
+/**
+ * cnblogs profile-session capability (task 0293, Chunk A).
+ *
+ * `login` opens the cnblogs post-edit entry (https://i.cnblogs.com/posts/edit, provisional — see
+ * `src/selectors.ts`) in a headed browser and resolves only once the site readiness predicate
+ * passes; `check` reopens the profile (headlessly, unless the operator passes `--headed` or the
+ * config sets `checkHeadedOnly`) and reports `verified` or `refused`; `open` just brings the
+ * window up. Arg parsing, profile precedence (`--profile` > `CNBLOGS_PROFILE_DIR` >
+ * `KK_BROWSER_PROFILE_DIR` > `~/.config/kk/browser-profiles/cnblogs`) and the exit codes
+ * (0 verified, 1 refused, 2 usage error) all live in the shared `runProfileCli`, so the publish
+ * preflight and this CLI apply one gate.
+ *
+ * The readiness predicate observes the site-owned Markdown editor (the grounded
+ * `input#post-title`, cnblogs.js:22/25/36, see `src/selectors.ts`); the login-redirect regex is
+ * provisional (see `src/selectors.ts`). A selector that never attaches is a refusal
+ * (`bun plugins/publishings/cnblogs-pub/src/profile-check.ts login` is the recovery), never
+ * silent success.
+ */
+import { runProfileCli } from '@gobing-ai/publish-harness/browser';
+import { CNBLOGS_CONFIG } from './selectors';
+
+if (import.meta.main) {
+    process.exit(await runProfileCli(CNBLOGS_CONFIG, Bun.argv.slice(2)));
+}

package/plugins/publishings/cnblogs-pub/src/selectors.ts

@@ -0,0 +1,104 @@
+/**
+ * cnblogs-pub selectors — every selector/URL/regex constant this channel resolves (task 0293).
+ *
+ * Grounding: the recovered extension adapter
+ * `.spur/memory/evidence/publish-ready-0288-0297-20261014-01/source/platforms/cnblogs.js` pins the
+ * three editor controls in both its fill (cnblogs.js:22-23, 25-26, 30) and its register map
+ * (cnblogs.js:35-37): `input#post-title`, `textarea#md-editor`, optional `textarea#summary`.
+ * Anything that evidence does not pin is **Provisional** and fails closed when absent — a missing
+ * control is a loud typed refusal, never a silent no-op or a broad fallback.
+ */
+import { trySelectors } from '@gobing-ai/publish-harness';
+import type { ChannelBrowserConfig } from '@gobing-ai/publish-harness/browser';
+import type { IsAuthenticatedPredicate } from '@gobing-ai/ts-browser-automation';
+
+/** Site-owned target slug; also the profile channel key (`CNBLOGS_PROFILE_DIR`). */
+export const CNBLOGS_TARGET = 'cnblogs';
+
+/**
+ * Post-edit entry where the article flow composes. **Provisional**: cnblogs.js runs inside an
+ * already-authenticated editor tab and never navigates (cnblogs.js fills in place only).
+ */
+export const CNBLOGS_EDIT_URL = 'https://i.cnblogs.com/posts/edit';
+
+/**
+ * Login/passport redirect marker. **Provisional**: cnblogs.js never observes a redirect URL;
+ * account.cnblogs.com/signin is cnblogs' known SSO entry. The readiness predicate below carries
+ * the real gate.
+ */
+export const CNBLOGS_LOGIN_URL_RE = /(account\.cnblogs\.com\/signin|\/signin)/;
+
+/**
+ * Article-editor selectors. The first three keys are **Grounded** (cnblogs.js:22-23, 25-26, 30
+ * and the cnblogs.js:35-37 register map); `categoryPanel`, `draftSave` and `publishButton` are
+ * **Provisional** semantic candidates from the task 0293 Design freeze — exact visible
+ * 保存草稿|存为草稿 and 发布|发布博文, bounded ordered resolution, no broad primary-button
+ * fallback, fail closed when absent.
+ */
+export const CNBLOGS_ARTICLE_SELECTORS = {
+    /** Title input. **Grounded** (cnblogs.js:22, 25, 36). */
+    titleInput: ['input#post-title'],
+    /** Markdown body textarea. **Grounded** (cnblogs.js:23, 26, 36); value + input events, never innerHTML. */
+    bodyEditor: ['textarea#md-editor'],
+    /** Optional digest/summary textarea. **Grounded** (cnblogs.js:30, 36); filled only when a digest is requested. */
+    summaryInput: ['textarea#summary'],
+    /**
+     * Category panel holding the account's existing categories as label-associated checkboxes.
+     * **Provisional** panel node (cnblogs.js never touches categories); the checkbox/label
+     * matching inside it is structural, not guessed.
+     */
+    categoryPanel: ['#cateOwner', '#categories'],
+    /**
+     * The exact-visible draft-save control(s). **Provisional** (task 0293 Design freeze);
+     * `text-is` exact match, most specific wording first, no other fallback.
+     */
+    draftSave: ['button:text-is("保存草稿")', 'button:text-is("存为草稿")'],
+    /**
+     * The exact-visible publish control(s). **Provisional** (task 0293 Design freeze); 发布博文
+     * first so the specific control wins over the bare 发布 wording — never a primary-button or
+     * submit fallback.
+     */
+    publishButton: ['button:text-is("发布博文")', 'button:text-is("发布")'],
+} as const;
+
+/** Keys of the selector map, for typed probes. */
+export type CnblogsArticleSelectorKey = keyof typeof CNBLOGS_ARTICLE_SELECTORS;
+
+/**
+ * Persisted draft/post receipt URL shapes. **Provisional**: cnblogs.js is a fill-only adapter and
+ * never reads a receipt; these are the edit-URL-gaining-`postId` and the public
+ * `/p/<id>.html` shapes the task 0293 Design freeze names. Only shapes in this list count as
+ * receipts, and only when they were not on screen before the save (fresh-signal rule).
+ */
+export const CNBLOGS_RECEIPT_URL_RES = [
+    /i\.cnblogs\.com\/posts\/edit\?[^\s#]*postId=\d+/,
+    /cnblogs\.com\/[^/\s]+\/p\/\d+\.html/,
+] as const;
+
+/** Login deadline for the operator CLI and the session gate (shared harness default). */
+export const CNBLOGS_LOGIN_TIMEOUT_MS = 180_000;
+
+/**
+ * Cnblogs-owned readiness predicate: no login redirect and the site-owned Markdown editor
+ * reachable (the grounded title input). Shared by the publish preflight and the operator profile
+ * CLI, so both apply one gate. The login-redirect regex is provisional (see
+ * `CNBLOGS_LOGIN_URL_RE`); the title-input probe carries the real gate.
+ */
+export const isCnblogsAuthenticated: IsAuthenticatedPredicate = async (page) => {
+    if (CNBLOGS_LOGIN_URL_RE.test(page.url())) return false;
+    return (await trySelectors(page, CNBLOGS_ARTICLE_SELECTORS.titleInput, { visible: false })).found;
+};
+
+/**
+ * Site-owned config for the shared session check and operator CLI (ADR-032). The check opens the
+ * post-edit entry (see `CNBLOGS_EDIT_URL`). The publish preflight never forwards
+ * `checkHeadedOnly`: it is the operator CLI's setting, and a refusal must never escalate to a
+ * headed window on its own.
+ */
+export const CNBLOGS_CONFIG: ChannelBrowserConfig = {
+    channel: CNBLOGS_TARGET,
+    homeUrl: CNBLOGS_EDIT_URL,
+    isAuthenticated: isCnblogsAuthenticated,
+    loginTimeoutMs: CNBLOGS_LOGIN_TIMEOUT_MS,
+    checkHeadedOnly: false,
+};

package/plugins/publishings/cnblogs-pub/tsconfig.json

@@ -0,0 +1,4 @@
+{
+    "extends": "../../../tooling/typescript/base.json",
+    "include": ["src", "tests"]
+}