@supportpages.io/wtfm 0.0.0-stage → 0.3.0

package/dist/actions.d.ts

@@ -0,0 +1,98 @@
+import { z } from 'zod';
+import type { Bridge } from './bridge.js';
+export declare const writerAction: z.ZodEnum<{
+    read_articles: "read_articles";
+    create_article: "create_article";
+    update_article: "update_article";
+    edit_article: "edit_article";
+    publish_article: "publish_article";
+    unpublish_article: "unpublish_article";
+    delete_article: "delete_article";
+    find_article_gaps: "find_article_gaps";
+    suggest_sections: "suggest_sections";
+    recommend_articles: "recommend_articles";
+    review_sections: "review_sections";
+    review_recommendations: "review_recommendations";
+    create_video_walkthrough: "create_video_walkthrough";
+    get_operation: "get_operation";
+    generate_help_centre: "generate_help_centre";
+}>;
+export type WriterAction = z.infer<typeof writerAction>;
+export declare const actionDecisionSchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        read_articles: "read_articles";
+        create_article: "create_article";
+        update_article: "update_article";
+        edit_article: "edit_article";
+        publish_article: "publish_article";
+        unpublish_article: "unpublish_article";
+        delete_article: "delete_article";
+        find_article_gaps: "find_article_gaps";
+        suggest_sections: "suggest_sections";
+        recommend_articles: "recommend_articles";
+        review_sections: "review_sections";
+        review_recommendations: "review_recommendations";
+        create_video_walkthrough: "create_video_walkthrough";
+        get_operation: "get_operation";
+        generate_help_centre: "generate_help_centre";
+    }>;
+    allowed: z.ZodBoolean;
+    execution: z.ZodEnum<{
+        local: "local";
+        remote: "remote";
+        hosted: "hosted";
+    }>;
+    required_scopes: z.ZodArray<z.ZodString>;
+    next_step: z.ZodNullable<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        requested_action: z.ZodEnum<{
+            read_articles: "read_articles";
+            create_article: "create_article";
+            update_article: "update_article";
+            edit_article: "edit_article";
+            publish_article: "publish_article";
+            unpublish_article: "unpublish_article";
+            delete_article: "delete_article";
+            find_article_gaps: "find_article_gaps";
+            suggest_sections: "suggest_sections";
+            recommend_articles: "recommend_articles";
+            review_sections: "review_sections";
+            review_recommendations: "review_recommendations";
+            create_video_walkthrough: "create_video_walkthrough";
+            get_operation: "get_operation";
+            generate_help_centre: "generate_help_centre";
+        }>;
+        missing_scopes: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            read: "read";
+            import: "import";
+            publish: "publish";
+            manage: "manage";
+            generate: "generate";
+        }>>>;
+        url: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Actions this Writer does not know are ignored and missing ones read as unadvertised,
+ * so a server that adds an action never breaks an older Writer (and vice versa). */
+export declare const writerCapabilitiesSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    actions: z.ZodPipe<z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodTransform<Partial<Record<"read_articles" | "create_article" | "update_article" | "edit_article" | "publish_article" | "unpublish_article" | "delete_article" | "find_article_gaps" | "suggest_sections" | "recommend_articles" | "review_sections" | "review_recommendations" | "create_video_walkthrough" | "get_operation" | "generate_help_centre", {
+        action: "read_articles" | "create_article" | "update_article" | "edit_article" | "publish_article" | "unpublish_article" | "delete_article" | "find_article_gaps" | "suggest_sections" | "recommend_articles" | "review_sections" | "review_recommendations" | "create_video_walkthrough" | "get_operation" | "generate_help_centre";
+        allowed: boolean;
+        execution: "local" | "remote" | "hosted";
+        required_scopes: string[];
+        next_step: {
+            code: string;
+            message: string;
+            requested_action: "read_articles" | "create_article" | "update_article" | "edit_article" | "publish_article" | "unpublish_article" | "delete_article" | "find_article_gaps" | "suggest_sections" | "recommend_articles" | "review_sections" | "review_recommendations" | "create_video_walkthrough" | "get_operation" | "generate_help_centre";
+            missing_scopes?: ("read" | "import" | "publish" | "manage" | "generate")[] | undefined;
+            url?: string | undefined;
+        } | null;
+    }>>, Record<string, unknown>>>;
+}, z.core.$strip>;
+export type ActionDecision = z.infer<typeof actionDecisionSchema>;
+/** Both terminal and MCP entrypoints use this read-only dispatcher. It never
+ * starts authentication or replaces hosted work with a local writer. */
+export declare function resolveAction(bridge: Bridge, action: WriterAction, articleId?: string): Promise<ActionDecision>;
+export declare function requireExecution(decision: ActionDecision, execution: ActionDecision['execution']): void;

package/dist/actions.js

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import { fail, publicError } from './errors.js';
+import { CLI_NAME } from './brand.js';
+export const writerAction = z.enum(['read_articles', 'create_article', 'update_article', 'edit_article', 'publish_article', 'unpublish_article', 'delete_article', 'find_article_gaps', 'suggest_sections', 'recommend_articles', 'review_sections', 'review_recommendations', 'create_video_walkthrough', 'get_operation', 'generate_help_centre']);
+export const actionDecisionSchema = z.object({ action: writerAction, allowed: z.boolean(), execution: z.enum(['local', 'remote', 'hosted']), required_scopes: z.array(z.string()),
+    next_step: z.object({ code: z.string().max(100), message: z.string().max(1000), requested_action: writerAction, missing_scopes: z.array(z.enum(['read', 'import', 'publish', 'manage', 'generate'])).optional(), url: z.url().optional() }).nullable(),
+}).refine(value => value.allowed === (value.next_step === null));
+/** Actions this Writer does not know are ignored and missing ones read as unadvertised,
+ * so a server that adds an action never breaks an older Writer (and vice versa). */
+export const writerCapabilitiesSchema = z.object({ version: z.literal(1), actions: z.record(z.string(), z.unknown()).transform((value, ctx) => {
+        const actions = {};
+        for (const [name, raw] of Object.entries(value)) {
+            if (!writerAction.safeParse(name).success)
+                continue;
+            const decision = actionDecisionSchema.safeParse(raw);
+            if (!decision.success) {
+                ctx.addIssue({ code: 'custom', message: `Invalid decision for ${name}`, path: [name] });
+                return z.NEVER;
+            }
+            actions[name] = decision.data;
+        }
+        return actions;
+    }) });
+const blocked = (action, code, message) => ({ action, allowed: false, execution: 'remote', required_scopes: [], next_step: { code, message, requested_action: action } });
+/** Both terminal and MCP entrypoints use this read-only dispatcher. It never
+ * starts authentication or replaces hosted work with a local writer. */
+export async function resolveAction(bridge, action, articleId) {
+    writerAction.parse(action);
+    const destination = await bridge.destination();
+    if (action === 'create_article' && (destination === 'local' || destination === 'none' && !bridge.api.configured())) {
+        return { action, allowed: true, execution: 'local', required_scopes: [], next_step: null };
+    }
+    if (!bridge.api.configured())
+        return blocked(action, 'authentication_required', `Sign in or create an account with ${CLI_NAME} login, then select a help centre and retry this action.`);
+    try {
+        if (destination !== 'hosted') {
+            await bridge.listProjects(); // Validate credentials before asking for a project.
+            return blocked(action, 'project_required', 'Select or create a help centre with supportpages_init, then retry this action.');
+        }
+        const context = await bridge.context();
+        let decision = context.repository_connection?.writer?.actions[action];
+        if (articleId) {
+            if (!/^[1-9][0-9]*$/.test(articleId))
+                fail('invalid_article', 'Choose an article ID from this project.');
+            const response = z.object({ version: z.literal(1), decision: actionDecisionSchema }).safeParse(await bridge.api.request('GET', `/projects/${context.project.id}/writer/capabilities?action_name=${action}&article_id=${articleId}`));
+            if (!response.success)
+                fail('invalid_response', 'The server returned an invalid action decision.');
+            decision = response.data.decision;
+        }
+        // Preserve legacy local authoring only when the server explicitly confirms
+        // there is no repository. Unknown or broken servers never imply local work.
+        if (!decision && action === 'create_article' && context.repository_connection?.state === 'not_connected') {
+            return { action, allowed: true, execution: 'local', required_scopes: ['read', 'import'], next_step: null };
+        }
+        if (!decision)
+            return blocked(action, 'server_update_required', 'Update the SupportPages server and Writer to use this action. The server did not advertise a supported action contract.');
+        if (decision.action !== action || decision.next_step && decision.next_step.requested_action !== action)
+            fail('invalid_response', 'The server returned a decision for another action.');
+        if (decision.next_step?.url) {
+            const url = new URL(decision.next_step.url);
+            const transport = new URL(bridge.api.origin);
+            const developmentUpgrade = bridge.api.dev && transport.hostname === url.hostname && url.protocol === 'https:';
+            if ((url.origin !== bridge.api.origin && !developmentUpgrade) || url.username || url.password)
+                fail('invalid_response', 'The server returned an invalid recovery link.');
+        }
+        return decision;
+    }
+    catch (error) {
+        const safe = publicError(error);
+        if (safe.code === 'invalid_credentials')
+            return blocked(action, 'authentication_required', 'Device sign-in has expired or was revoked. Sign in again, then retry this action.');
+        if (safe.code === 'not_found')
+            return blocked(action, 'resource_unavailable', 'This project or article is unavailable. Restore access or select an accessible resource before retrying.');
+        throw error;
+    }
+}
+export function requireExecution(decision, execution) {
+    if (!decision.allowed) {
+        const next = decision.next_step;
+        const guidance = next.url ? ` Open: ${next.url}` : next.missing_scopes?.length ? ` Run ${CLI_NAME} login --scopes ${next.missing_scopes.join(',')}, or use supportpages_request_permissions.` : '';
+        fail(next.code, next.message + guidance, { writer_action: decision });
+    }
+    if (decision.execution !== execution)
+        fail('hosted_action_required', 'This action runs in SupportPages. Use the hosted action tool; do not launch a local writer.', { writer_action: decision });
+}
+//# sourceMappingURL=actions.js.map

package/dist/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}

package/dist/agent-settings.d.ts

@@ -0,0 +1,22 @@
+import { Workspace } from './workspace.js';
+type SettingsWorkspace = {
+    ws: Workspace;
+    stateRoot: string;
+};
+export declare const efforts: Record<string, string[]>;
+export declare const modelValid: (value: unknown) => value is string;
+export declare const settingsFile: (bridge: SettingsWorkspace) => string;
+export declare function modelSettings(agent: string, saved?: unknown): {
+    model: string | null;
+    effort: string | null;
+};
+export declare function readAgentSettings(bridge: SettingsWorkspace): Promise<{
+    [x: string]: unknown;
+    models?: Record<string, unknown> | undefined;
+    agents?: ("claude" | "codex")[] | undefined;
+}>;
+export declare function executionSettings(bridge: SettingsWorkspace, agent: string): Promise<{
+    model: string | null;
+    effort: string | null;
+}>;
+export {};

package/dist/agent-settings.js

@@ -0,0 +1,35 @@
+import { fail } from './errors.js';
+import { z } from 'zod';
+import { CLI_NAME } from './brand.js';
+export const efforts = { claude: ['low', 'medium', 'high', 'xhigh', 'max'], codex: ['minimal', 'low', 'medium', 'high', 'xhigh'] };
+export const modelValid = (value) => typeof value === 'string' && value.length <= 200 && /^[a-zA-Z0-9][a-zA-Z0-9._:/\[\]-]*$/.test(value);
+export const settingsFile = (bridge) => `${bridge.stateRoot}/setup/settings.json`;
+// Undefined means SupportPages.io defaults; null explicitly inherits the agent setting.
+export function modelSettings(agent, saved = {}) {
+    if (!efforts[agent])
+        fail('invalid_agent', 'Choose Claude Code or Codex.');
+    const values = z.object({ model: z.unknown().optional(), effort: z.unknown().optional() }).safeParse(saved);
+    if (!values.success)
+        fail('invalid_configuration', `Invalid coding-agent settings. Run ${CLI_NAME} configure to change them.`);
+    const model = values.data.model === undefined ? (agent === 'claude' ? 'sonnet' : null) : values.data.model;
+    const effort = values.data.effort === undefined ? (agent === 'claude' ? 'low' : null) : values.data.effort;
+    if (model !== null && !modelValid(model) || effort !== null && (typeof effort !== 'string' || !efforts[agent].includes(effort))) {
+        fail('invalid_configuration', `Invalid coding-agent model or effort. Run ${CLI_NAME} configure to change it.`);
+    }
+    return { model, effort };
+}
+export async function readAgentSettings(bridge) {
+    const value = await bridge.ws.exists(settingsFile(bridge)) ? await bridge.ws.json(settingsFile(bridge)) : {};
+    const result = z.object({
+        models: z.record(z.string(), z.unknown()).optional(),
+        agents: z.array(z.enum(['claude', 'codex'])).min(1).max(2).refine(agents => new Set(agents).size === agents.length).optional(),
+    }).passthrough().safeParse(value);
+    if (!result.success) {
+        fail('invalid_configuration', 'The saved coding-agent settings are invalid.');
+    }
+    return result.data;
+}
+export async function executionSettings(bridge, agent) {
+    return modelSettings(agent, (await readAgentSettings(bridge)).models?.[agent] ?? {});
+}
+//# sourceMappingURL=agent-settings.js.map

package/dist/agent-settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-settings.js","sourceRoot":"","sources":["../src/agent-settings.ts"],"names":[],"mappings":"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"}

package/dist/api.d.ts

@@ -0,0 +1,14 @@
+export declare function developmentMode(value?: string): boolean;
+export declare function defaultOrigin(dev: boolean): string;
+export declare function connectionStateRoot(origin: string, dev: boolean): string;
+export declare function apiOrigin(value: string, dev?: boolean): string;
+export declare const WRITER_FEATURES: readonly ["generate_help_centre"];
+export declare class ApiClient {
+    private token?;
+    private fetcher;
+    dev: boolean;
+    origin: string;
+    constructor(origin: string, token?: string | undefined, fetcher?: typeof fetch, dev?: boolean);
+    configured(): boolean;
+    request(method: string, route: string, body?: FormData | object, idempotencyKey?: string, timeoutMs?: number): Promise<unknown>;
+}

package/dist/api.js

@@ -0,0 +1,159 @@
+import { createHash } from 'node:crypto';
+import { fail } from './errors.js';
+import { articleCapacitySchema } from './schema.js';
+import { capacityMessage } from './capacity.js';
+import { connectionFailure } from './development-tls.js';
+import { CLI_NAME } from './brand.js';
+export function developmentMode(value) {
+    if (value === undefined || value === 'false' || value === '0')
+        return false;
+    if (value === 'true' || value === '1')
+        return true;
+    fail('invalid_configuration', 'SUPPORTPAGES_DEV must be true, false, 1 or 0.');
+}
+export function defaultOrigin(dev) {
+    return dev ? 'https://app.lvh.me:3443' : 'https://app.supportpages.io';
+}
+export function connectionStateRoot(origin, dev) {
+    return dev ? `.rtfm/supportpages/dev/${createHash('sha256').update(origin).digest('hex').slice(0, 16)}` : '.rtfm/supportpages';
+}
+export function apiOrigin(value, dev = false) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        fail('invalid_configuration', 'SUPPORTPAGES_API_URL must be an HTTP(S) origin.');
+    }
+    const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    const local = loopback || url.hostname === 'app.lvh.me';
+    if (dev && !local)
+        fail('invalid_configuration', 'Dev mode requires localhost, loopback, or app.lvh.me.');
+    if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && (loopback || (dev && local)))) || url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
+        fail('invalid_configuration', 'Use an HTTPS API origin, or HTTP on loopback (app.lvh.me requires --dev), without credentials or a path.');
+    }
+    return url.origin;
+}
+export const WRITER_FEATURES = ['generate_help_centre'];
+export class ApiClient {
+    token;
+    fetcher;
+    dev;
+    origin;
+    constructor(origin, token, fetcher = fetch, dev = false) {
+        this.token = token;
+        this.fetcher = fetcher;
+        this.dev = dev;
+        this.origin = apiOrigin(origin, dev);
+    }
+    configured() { return Boolean(this.token); }
+    async request(method, route, body, idempotencyKey, timeoutMs = 60_000) {
+        if (!this.token)
+            fail('missing_credentials', `This device is not signed in to SupportPages.io. In the terminal, run ${CLI_NAME} publish to host locally saved articles, or ${CLI_NAME} login; then call supportpages_init.`);
+        // Name the optional actions this Writer understands, so the server lists
+        // them in capability maps only for clients that can parse them.
+        const headers = { Authorization: `Bearer ${this.token}`, Accept: 'application/json', 'X-SupportPages-Writer-Features': WRITER_FEATURES.join(',') };
+        if (idempotencyKey)
+            headers['Idempotency-Key'] = idempotencyKey;
+        let payload;
+        if (body instanceof FormData)
+            payload = body;
+        else if (body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            payload = JSON.stringify(body);
+        }
+        let response;
+        try {
+            response = await this.fetcher(`${this.origin}/api/v1${route}`, { method, headers, body: payload, redirect: 'error', signal: AbortSignal.timeout(timeoutMs) });
+        }
+        catch (error) {
+            connectionFailure(error, this.dev, 'SupportPages.io could not be reached. Check the connection and retry.');
+        }
+        if (!response.ok) {
+            const code = { 401: 'invalid_credentials', 403: 'permission_denied', 404: 'not_found', 409: 'revision_conflict', 413: 'bundle_too_large', 422: 'invalid_artifact', 429: 'rate_limited' }[response.status] ?? 'remote_error';
+            // Decode only bounded, recognised error codes. Never echo arbitrary server
+            // messages, proxy diagnostics or user-controlled response fields.
+            const known = {
+                invalid_content: { status: 422, message: 'The supplied article content is invalid. Read the article and preserve its content format before retrying.' },
+                unsupported_article_format: { status: 422, message: 'Preserve this article’s content format: structured content for illustrated articles, Markdown for API-authored articles.' },
+                generation_running: { status: 409, message: 'Wait for the current generation to finish, or keep the local preview as an editable draft in SupportPages.' },
+                article_deleted: { status: 409, message: 'This article was deleted remotely. Restore it in SupportPages.io before updating it; it will not be recreated automatically.' },
+                plan_limit: { status: 403, message: 'Your account’s article hosting limit has been reached. Free up article capacity or update your plan, then retry the saved upload. Reconnecting will not resolve this limit.' },
+                permission_denied: { status: 403, message: `This token does not have permission for the requested operation. Check its scopes and project access; reconnect with ${CLI_NAME} init if needed.` },
+                repository_connection_required: { status: 403, message: 'Connect a repository in the web app before assigning sections. Individual unsectioned articles do not require a repository connection.' },
+                run_closed: { status: 409, message: 'This generation attempt is closed. The saved draft and your local files are preserved; do not overwrite browser edits.' },
+                published_article: { status: 409, message: 'This article is already published. Local uploads cannot overwrite it; review it in the web app.' },
+            };
+            const reader = response.body?.getReader();
+            let recognised;
+            let capacity;
+            try {
+                const chunks = [];
+                let size = 0;
+                if (reader)
+                    while (size <= 8192) {
+                        const item = await reader.read();
+                        if (item.done)
+                            break;
+                        size += item.value.length;
+                        if (size <= 8192)
+                            chunks.push(item.value);
+                    }
+                const value = size <= 8192 ? JSON.parse(Buffer.concat(chunks).toString()) : null;
+                const candidate = value?.error?.code;
+                if (typeof candidate === 'string' && Object.hasOwn(known, candidate) && known[candidate]?.status === response.status)
+                    recognised = candidate;
+                if (recognised === 'plan_limit') {
+                    const parsed = articleCapacitySchema.safeParse(value?.error?.details?.article_capacity);
+                    if (parsed.success && !parsed.data.can_create)
+                        capacity = parsed.data;
+                }
+            }
+            catch { /* Older servers and HTML errors retain their HTTP fallback. */ }
+            finally {
+                await reader?.cancel().catch(() => { });
+                reader?.releaseLock();
+            }
+            if (recognised) {
+                if (capacity)
+                    fail(recognised, `${capacityMessage(capacity)} Then retry the saved upload; no regeneration is needed.`, { status: response.status, article_capacity: capacity });
+                const message = recognised === 'plan_limit' && !/\/(article_imports|generation_runs)(\/|$)/.test(route)
+                    ? 'Your account’s plan limit for this operation has been reached. Check your plan and available capacity before retrying.'
+                    : known[recognised].message;
+                fail(recognised, message, { status: response.status });
+            }
+            fail(code, `SupportPages.io returned HTTP ${response.status}.`, { status: response.status });
+        }
+        if (!response.headers.get('content-type')?.includes('application/json'))
+            fail('invalid_response', 'The API did not return JSON. Verify the RTFM integration is installed on the app host.');
+        const reader = response.body?.getReader();
+        if (!reader)
+            fail('invalid_response', 'The API returned an empty response.');
+        const chunks = [];
+        let size = 0;
+        try {
+            while (true) {
+                const chunk = await reader.read();
+                if (chunk.done)
+                    break;
+                size += chunk.value.byteLength;
+                if (size > 4 * 1024 * 1024) {
+                    await reader.cancel();
+                    fail('invalid_response', 'The API response exceeded the size limit.');
+                }
+                chunks.push(chunk.value);
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        const data = Buffer.concat(chunks).toString('utf8');
+        try {
+            return JSON.parse(data);
+        }
+        catch {
+            fail('invalid_response', 'The API returned malformed JSON.');
+        }
+    }
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/article-link.d.ts

@@ -0,0 +1,16 @@
+import type { Run } from './runs.js';
+export declare const articleChatInstruction = "Keep user-facing chat focused on the SupportPages.io editor link, article progress, review and publication. Do not mention local assets, saved files, filesystem paths, output directories, filenames, rendering scripts or validation reports in routine progress, completion or failure messages. These are internal execution details, not deliverables to list or download. Explain failures in terms of their effect on the article and the next action, with the editor link when available. If delivery fails, say that the latest changes could not be confirmed in the editor; do not claim the editor is up to date or reassure the user that assets are saved locally. Share technical file details only when the user explicitly asks for them.";
+export declare const showArticleLinkInstruction: string;
+/** Local workspaces have no editor: the saved Markdown path is the deliverable. */
+export declare const localChatInstruction = "This folder saves articles locally; there is no SupportPages.io editor or help centre for it. The saved Markdown path is the deliverable: show it in your completion message, with the number of screenshots. Keep progress messages concise and free of intermediate filenames, rendering scripts or validation reports. Never ask whether to publish automatically; hosting needs an account. If the user explicitly asks to host or publish saved local articles, ask whether to sign in or create a free SupportPages.io account, then use supportpages_publish. Any hosting offer comes from complete_article as hosting_invitation; do not add your own.";
+export declare const localLinkInstruction: string;
+export declare function articleLink(run: Run): {
+    editor_url: string | null;
+    link_message: string;
+    link_instructions: string;
+};
+/** Keep the URL visible as a separate MCP text item as well as structured data. */
+export declare function articleLinkContent(value: unknown): {
+    type: "text";
+    text: string;
+}[];

package/dist/article-link.js

@@ -0,0 +1,25 @@
+export const articleChatInstruction = 'Keep user-facing chat focused on the SupportPages.io editor link, article progress, review and publication. Do not mention local assets, saved files, filesystem paths, output directories, filenames, rendering scripts or validation reports in routine progress, completion or failure messages. These are internal execution details, not deliverables to list or download. Explain failures in terms of their effect on the article and the next action, with the editor link when available. If delivery fails, say that the latest changes could not be confirmed in the editor; do not claim the editor is up to date or reassure the user that assets are saved locally. Share technical file details only when the user explicitly asks for them.';
+export const showArticleLinkInstruction = articleChatInstruction + ' Always show the returned article link in your next user-facing message, before launching or retrying the writer. Repeat it even if this article already existed, the link was shown earlier, or the operation failed. Do not wait for article text, images or completion. If no confirmed link is available, say so and explain the reported problem; never invent a URL. Showing a link does not mean opening the browser or publishing.';
+/** Local workspaces have no editor: the saved Markdown path is the deliverable. */
+export const localChatInstruction = 'This folder saves articles locally; there is no SupportPages.io editor or help centre for it. The saved Markdown path is the deliverable: show it in your completion message, with the number of screenshots. Keep progress messages concise and free of intermediate filenames, rendering scripts or validation reports. Never ask whether to publish automatically; hosting needs an account. If the user explicitly asks to host or publish saved local articles, ask whether to sign in or create a free SupportPages.io account, then use supportpages_publish. Any hosting offer comes from complete_article as hosting_invitation; do not add your own.';
+export const localLinkInstruction = localChatInstruction + ' Do not invent an editor URL; there is none for this article.';
+export function articleLink(run) {
+    if (run.export_path)
+        return { editor_url: null, link_message: `Saved to ${run.export_path}`, link_instructions: localLinkInstruction };
+    const editor_url = run.remote?.editor_url ?? run.progress?.article?.editor_url ?? null;
+    return { editor_url, link_message: editor_url ? `View article: ${editor_url}` : 'No confirmed article link is available yet.',
+        link_instructions: showArticleLinkInstruction };
+}
+/** Keep the URL visible as a separate MCP text item as well as structured data. */
+export function articleLinkContent(value) {
+    if (!value || typeof value !== 'object')
+        return [];
+    const data = value;
+    const url = data.editor_url ?? data.article_run?.editor_url ?? data.details?.editor_url ?? data.article?.editor_url;
+    if (typeof url !== 'string')
+        return [];
+    // Guidance is already in server instructions and structured responses. Keep
+    // this visible text item useful without repeating that policy on every call.
+    return [{ type: 'text', text: `View article: ${url}` }];
+}
+//# sourceMappingURL=article-link.js.map

package/dist/article-link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"article-link.js","sourceRoot":"","sources":["../src/article-link.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,sBAAsB,GAAG,6tBAA6tB,CAAC;AAEpwB,MAAM,CAAC,MAAM,0BAA0B,GAAG,sBAAsB,GAAG,4aAA4a,CAAC;AAEhf,mFAAmF;AACnF,MAAM,CAAC,MAAM,oBAAoB,GAAG,goBAAgoB,CAAC;AAErqB,MAAM,CAAC,MAAM,oBAAoB,GAAG,oBAAoB,GAAG,+DAA+D,CAAC;AAE3H,MAAM,UAAU,WAAW,CAAC,GAAQ;IAClC,IAAI,GAAG,CAAC,WAAW;QAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,EAAE,YAAY,GAAG,CAAC,WAAW,EAAE,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,CAAC;IACvI,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,IAAI,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,IAAI,IAAI,CAAC;IACvF,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,CAAC,CAAC,CAAC,iBAAiB,UAAU,EAAE,CAAC,CAAC,CAAC,6CAA6C;QAC3H,iBAAiB,EAAE,0BAA0B,EAAE,CAAC;AACpD,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IACnD,MAAM,IAAI,GAAG,KAA4B,CAAC;IAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,WAAW,EAAE,UAAU,IAAI,IAAI,CAAC,OAAO,EAAE,UAAU,IAAI,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC;IACpH,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IACvC,4EAA4E;IAC5E,6EAA6E;IAC7E,OAAO,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,iBAAiB,GAAG,EAAE,EAAE,CAAC,CAAC;AACnE,CAAC"}

package/dist/artifacts.d.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { type Article, type Manifest } from './schema.js';
+import { Workspace } from './workspace.js';
+export declare const sha256: (data: string | Buffer) => string;
+export declare function canonical(value: unknown): string;
+export declare function parse<T>(schema: z.ZodType<T>, value: unknown, code?: string): T;
+export type Snapshot = {
+    article: Article;
+    articleBytes: Buffer;
+    images: {
+        block_id: string;
+        filename: string;
+        bytes: Buffer;
+    }[];
+    warnings: string[];
+};
+/** Read the latest usable preview without requiring finished screenshots or lint. */
+export declare function progressSnapshot(ws: Workspace, dir: string, options?: {
+    imageHashes?: Record<string, string>;
+    fallbackDir?: string;
+}): Promise<Snapshot | undefined>;
+export declare function snapshot(ws: Workspace, dir: string, startedAt?: string): Promise<Snapshot>;
+export declare function createManifest(snap: Snapshot, metadata: Pick<Manifest, 'local_article_id' | 'run_id' | 'skills_version' | 'source_commit' | 'source_dirty' | 'section_id'>): Manifest;
+export declare function verifyBundle(ws: Workspace, dir: string): Promise<{
+    manifest: {
+        bundle_version: 1;
+        local_article_id: string;
+        run_id: string;
+        skills_version: string;
+        source_commit: string | null;
+        source_dirty: boolean;
+        section_id: string | null;
+        article_sha256: string;
+        images: {
+            block_id: string;
+            filename: string;
+            sha256: string;
+            size: number;
+            mime_type: "image/png";
+        }[];
+        bundle_hash: string;
+    };
+    snap: Snapshot;
+}>;
+export declare function preview(snap: Snapshot): string;