@supportpages.io/wtfm 0.0.0-stage → 0.3.0

package/dist/progress.js

@@ -0,0 +1,224 @@
+import { execFile } from 'node:child_process';
+import { z } from 'zod';
+import { articleSchema, manifestSchema, remoteArticleSchema } from './schema.js';
+import { createManifest, parse, sha256, progressSnapshot } from './artifacts.js';
+import { exportArticle } from './export.js';
+import path from 'node:path';
+import { fail, publicError } from './errors.js';
+export const progressResponse = z.object({ run_id: z.uuid(), attempt: z.uuid(), state: z.enum(['running', 'failed', 'interrupted', 'cancelled', 'complete', 'kept', 'discarded']), sequence: z.number().int().nonnegative(), article: remoteArticleSchema });
+export async function openPreview(url) {
+    const env = { ...process.env };
+    delete env.SUPPORTPAGES_API_TOKEN;
+    delete env.SUPPORTPAGES_API_TOKEN_FILE;
+    if (!['darwin', 'linux'].includes(process.platform))
+        return false;
+    return new Promise(resolve => execFile(process.platform === 'darwin' ? 'open' : 'xdg-open', [url], { env, timeout: 5000 }, error => resolve(!error)));
+}
+/** Session-owned relay. The host writer only writes artifacts, never credentials. */
+export class ProgressRelay {
+    bridge;
+    open;
+    timer;
+    running = false;
+    failures = 0;
+    generation = 0;
+    constructor(bridge, open = openPreview) {
+        this.bridge = bridge;
+        this.open = open;
+    }
+    stop() { this.running = false; this.generation++; clearTimeout(this.timer); }
+    start(id) {
+        this.stop();
+        this.running = true;
+        this.failures = 0;
+        this.schedule(id, 0);
+    }
+    schedule(id, delay) {
+        if (!this.running)
+            return;
+        const generation = this.generation;
+        this.timer = setTimeout(async () => {
+            try {
+                await this.tick(id, true, generation);
+                if (generation === this.generation)
+                    this.failures = 0;
+            }
+            catch (error) {
+                if (generation !== this.generation)
+                    return;
+                this.failures++;
+                const safe = publicError(error);
+                await this.bridge.lock(async () => {
+                    if (generation !== this.generation)
+                        return;
+                    const run = await this.bridge.runs.read(id);
+                    if (run.progress)
+                        await this.bridge.runs.save({ ...run, progress: { ...run.progress, sync_error: safe.message, sync_failures: (run.progress.sync_failures ?? 0) + 1 } });
+                }).catch(() => { });
+                if (generation === this.generation && !['network_error', 'remote_error', 'rate_limited', 'workspace_busy'].includes(safe.code))
+                    this.stop();
+            }
+            if (generation !== this.generation)
+                return;
+            this.schedule(id, this.failures ? Math.min(60_000, 2000 * 2 ** this.failures) : 2000);
+        }, delay);
+        this.timer.unref();
+    }
+    async ensureStartedUnlocked(id) {
+        let run = await this.bridge.runs.read(id);
+        if (!run.progress || run.progress.article)
+            return run;
+        let result;
+        try {
+            result = parse(progressResponse, await this.bridge.api.request('POST', `/projects/${run.project_id}/generation_runs`, {
+                run_id: run.id, local_article_id: run.local_article_id, attempt: run.progress.attempt,
+                title: run.title, article_type: run.article_type ?? 'how-to', section_id: run.section_id,
+            }), 'invalid_response');
+        }
+        catch (error) {
+            await this.bridge.runs.save({ ...run, progress: { ...run.progress, sync_error: publicError(error).message } });
+            throw error;
+        }
+        run = { ...run, progress: { ...run.progress, article: result.article, last_heartbeat: Date.now(), sync_error: undefined } };
+        await this.bridge.runs.save(run);
+        if (result.state !== 'running')
+            fail('run_closed', 'This preview is closed. Use retry_article after stopping the writer.');
+        return run;
+    }
+    async tick(id, scheduled = false, generation = this.generation) {
+        if (scheduled) {
+            if (!this.running || generation !== this.generation)
+                return;
+            const observed = await this.bridge.runs.read(id);
+            // Shutdown may finish while this read is in flight. Do not enqueue a new
+            // workspace operation after close() has drained the existing queue.
+            if (!this.running || generation !== this.generation)
+                return;
+            // Watching for an explicit finish must not compete with unrelated
+            // workspace operations while no preview work or finish request exists.
+            // Recheck every condition under the lock when there is work to perform.
+            if (!observed.writer_completed_at && ((!observed.progress && observed.project_id) || observed.phase === 'prepared'))
+                return;
+        }
+        const complete = await this.bridge.lock(async () => {
+            if (scheduled && (!this.running || generation !== this.generation))
+                return;
+            let run = await this.bridge.runs.read(id);
+            if (run.writer_completed_at && !run.remote && !run.error && run.phase !== 'saved' && ['prepared', 'finalized'].includes(run.status))
+                return true;
+            if (run.status !== 'prepared') {
+                this.stop();
+                return;
+            }
+            // Preparation arms observation; only actual writer entry (or the host's
+            // explicit started event) enables heartbeats and preview uploads.
+            if (run.phase === 'prepared')
+                return;
+            if (run.phase !== 'writing') {
+                this.stop();
+                return;
+            }
+            if (!run.project_id) {
+                await this.exportLocalUnlocked(run);
+                return;
+            }
+            if (!run.progress)
+                return;
+            run = await this.ensureStartedUnlocked(id);
+            let progress = run.progress;
+            const route = `/projects/${run.project_id}/generation_runs/${run.id}`;
+            if (Date.now() - (progress.last_heartbeat ?? 0) >= 30_000) {
+                const response = parse(progressResponse, await this.bridge.api.request('POST', `${route}/event`, { event: 'heartbeat', attempt: progress.attempt }), 'invalid_response');
+                progress = { ...progress, article: response.article, last_heartbeat: Date.now(), sync_error: undefined };
+                run = { ...run, progress };
+                await this.bridge.runs.save(run);
+            }
+            if (progress.pending) {
+                await this.sendPendingUnlocked(id);
+                return;
+            }
+            const snap = await progressSnapshot(this.bridge.ws, run.artifact_dir, { imageHashes: progress.image_hashes });
+            if (!snap)
+                return;
+            const articleHash = sha256(snap.articleBytes);
+            if (articleHash === progress.article_hash && !snap.images.length)
+                return;
+            const manifest = createManifest(snap, { local_article_id: run.local_article_id, run_id: run.id, skills_version: run.skills_version, source_commit: null, source_dirty: true, section_id: run.section_id });
+            // Persist the exact request before sending: a lost response must retry the
+            // same sequence and bytes, even when the writer has produced newer files.
+            const pending = progress.pending ?? { sequence: progress.sequence + 1, directory: `${this.bridge.stateRoot}/runs/${run.id}/progress-pending` };
+            if (!progress.pending) {
+                await this.bridge.ws.writeJson(`${pending.directory}/manifest.json`, manifest);
+                await this.bridge.ws.write(`${pending.directory}/article.json`, snap.articleBytes);
+                for (const image of snap.images)
+                    await this.bridge.ws.write(`${pending.directory}/${image.filename}`, image.bytes);
+                progress = { ...progress, pending };
+                await this.bridge.runs.save({ ...run, progress });
+            }
+            await this.sendPendingUnlocked(id);
+        });
+        // Reuse final validation/import outside the operation lock. Only an explicit
+        // successful writer finish can reach here; files or silence alone never do.
+        // Delivery copy is left for the parent's complete_article call, so the relay
+        // does not consume the one-time invitation or publication question.
+        if (complete && (!scheduled || (this.running && generation === this.generation))) {
+            await this.bridge.complete({ run_id: id, completed: true }, { deliver: false });
+        }
+    }
+    async exportLocalUnlocked(run) {
+        if (await this.bridge.destination() !== 'local')
+            fail('destination_mismatch', 'This local writer no longer belongs to the current destination.');
+        const local = await this.bridge.local();
+        if (!local)
+            fail('local_required', 'Local article settings are missing.');
+        const directory = run.local_export?.directory ?? local.export_dir;
+        const slug = run.artifact_dir.split('/').at(-1);
+        try {
+            const snap = await progressSnapshot(this.bridge.ws, run.artifact_dir, {
+                fallbackDir: path.posix.join(directory, slug),
+            });
+            if (!snap)
+                return;
+            const exported = await exportArticle(this.bridge.ws, snap, run.artifact_dir, directory, slug);
+            if (run.local_export?.markdown_path !== exported.markdown_path || run.local_export?.sync_error) {
+                await this.bridge.runs.save({ ...run, local_export: { directory, markdown_path: exported.markdown_path } });
+            }
+        }
+        catch (error) {
+            // Keep writing and retry the export on the next observation. Preview
+            // delivery errors do not mean that generation itself has failed.
+            await this.bridge.runs.save({ ...run, local_export: { ...run.local_export, directory, sync_error: publicError(error).message } });
+        }
+    }
+    async sendPendingUnlocked(id) {
+        const run = await this.bridge.runs.read(id);
+        const progress = run.progress;
+        if (!progress.pending)
+            return;
+        const { directory, sequence } = progress.pending;
+        const manifest = parse(manifestSchema, await this.bridge.ws.json(`${directory}/manifest.json`));
+        const form = new FormData();
+        form.set('attempt', progress.attempt);
+        form.set('sequence', String(sequence));
+        form.set('manifest', JSON.stringify(manifest));
+        form.set('article', new Blob([new Uint8Array(await this.bridge.ws.read(`${directory}/article.json`))]), 'article.json');
+        for (const image of manifest.images)
+            form.set(`images[${image.block_id}]`, new Blob([new Uint8Array(await this.bridge.ws.read(`${directory}/${image.filename}`, 10 * 1024 * 1024))], { type: 'image/png' }), image.filename);
+        const response = parse(progressResponse, await this.bridge.api.request('POST', `/projects/${run.project_id}/generation_runs/${id}/milestones`, form, manifest.bundle_hash), 'invalid_response');
+        const article = parse(articleSchema, JSON.parse((await this.bridge.ws.read(`${directory}/article.json`)).toString()));
+        const ids = new Set(article.blocks.filter(b => b.type === 'section' && b.has_image).map(b => b.id));
+        const hashes = Object.fromEntries(Object.entries(progress.image_hashes ?? {}).filter(([key]) => ids.has(key)));
+        for (const image of manifest.images)
+            hashes[image.block_id] = image.sha256;
+        const shouldOpen = run.open_when_ready && !progress.open_attempted;
+        await this.bridge.runs.save({ ...run, progress: { ...progress, article: response.article, sequence: response.sequence,
+                pending: undefined, article_hash: manifest.article_sha256, image_hashes: hashes, last_heartbeat: Date.now(), sync_error: undefined,
+                open_attempted: progress.open_attempted || Boolean(shouldOpen) } });
+        if (shouldOpen) {
+            const opened = await this.open(response.article.editor_url).catch(() => false);
+            const current = await this.bridge.runs.read(id);
+            await this.bridge.runs.save({ ...current, progress: { ...current.progress, browser_opened: opened } });
+        }
+    }
+}
+//# sourceMappingURL=progress.js.map

package/dist/progress.js.map

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

package/dist/reminders.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+export declare const defaultConfigDir: () => string;
+export type Benefit = {
+    readonly id: string;
+    readonly category: string;
+    readonly message: string;
+};
+export type ReminderState<Invitation> = {
+    version: 1;
+    enabled: boolean;
+    count: number;
+    articles: Record<string, Invitation | null>;
+    history: string[];
+    last_category?: string;
+};
+export declare function reminderStateSchema<Invitation>(invitation: z.ZodType<Invitation>): z.ZodType<ReminderState<Invitation>>;
+/** Device-local reminder journal: one private state file per scope, serialized
+ * across processes and checkouts. Shared by the repository and hosting reminders. */
+export declare class ReminderJournal<Invitation> {
+    private directory;
+    private schema;
+    constructor(directory: string, schema: z.ZodType<ReminderState<Invitation>>);
+    transaction<T>(scope: unknown[], operation: (state: ReminderState<Invitation>) => T): Promise<T>;
+}
+/** Claim one delivery per article before returning: a replay cannot emit twice,
+ * even if a process exits before saving its workspace journal or delivering the
+ * response to the host. Returns false when the article was already counted. */
+export declare function claimDelivery<Invitation>(state: ReminderState<Invitation>, articleId: string): boolean;
+/** Rotate through a catalogue: unused copy first, preferring a different category
+ * from the previous invitation; a new cycle starts only once everything eligible was used. */
+export declare function selectBenefit<B extends Benefit>(state: ReminderState<unknown>, eligible: readonly B[]): B;

package/dist/reminders.js

@@ -0,0 +1,73 @@
+import { createHash } from 'node:crypto';
+import { mkdir } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { z } from 'zod';
+import { Workspace } from './workspace.js';
+export const defaultConfigDir = () => path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'supportpages');
+export function reminderStateSchema(invitation) {
+    return z.object({
+        version: z.literal(1), enabled: z.boolean(), count: z.number().int().nonnegative(),
+        articles: z.record(z.string(), invitation.nullable()),
+        history: z.array(z.string()), last_category: z.string().optional(),
+    });
+}
+const initial = () => ({ version: 1, enabled: true, count: 0, articles: {}, history: [] });
+/** Device-local reminder journal: one private state file per scope, serialized
+ * across processes and checkouts. Shared by the repository and hosting reminders. */
+export class ReminderJournal {
+    directory;
+    schema;
+    constructor(directory, schema) {
+        this.directory = directory;
+        this.schema = schema;
+    }
+    async transaction(scope, operation) {
+        const key = createHash('sha256').update(JSON.stringify(scope)).digest('hex');
+        const root = path.join(this.directory, key);
+        await mkdir(root, { recursive: true, mode: 0o700 });
+        const ws = await Workspace.create(root);
+        // Separate processes/checkouts can complete together. Retry lock contention,
+        // but never remove a lock owned by another process (including after a crash).
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await ws.lock(async () => {
+                    const state = await ws.exists('state.json') ? this.schema.parse(await ws.json('state.json')) : initial();
+                    const result = operation(state);
+                    await ws.writeJson('state.json', state);
+                    return result;
+                });
+            }
+            catch (error) {
+                if (error.code !== 'workspace_busy' || attempt >= 100)
+                    throw error;
+                await delay(20);
+            }
+        }
+    }
+}
+/** Claim one delivery per article before returning: a replay cannot emit twice,
+ * even if a process exits before saving its workspace journal or delivering the
+ * response to the host. Returns false when the article was already counted. */
+export function claimDelivery(state, articleId) {
+    if (Object.hasOwn(state.articles, articleId))
+        return false;
+    state.articles[articleId] = null;
+    state.count++;
+    return true;
+}
+/** Rotate through a catalogue: unused copy first, preferring a different category
+ * from the previous invitation; a new cycle starts only once everything eligible was used. */
+export function selectBenefit(state, eligible) {
+    let unused = eligible.filter(benefit => !state.history.includes(benefit.id));
+    if (!unused.length) {
+        state.history = [];
+        unused = [...eligible];
+    }
+    const benefit = unused.find(benefit => benefit.category !== state.last_category) ?? unused[0];
+    state.history.push(benefit.id);
+    state.last_category = benefit.category;
+    return benefit;
+}
+//# sourceMappingURL=reminders.js.map

package/dist/reminders.js.map

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

package/dist/replace-connection.d.ts

@@ -0,0 +1,6 @@
+import type { Bridge } from './bridge.js';
+/** CLI-only, after the user confirms moving this folder to another help centre. The device credential is untouched. */
+export declare function replaceConnection(bridge: Bridge, expectedProjectId: string, projectId: string): Promise<{
+    archive: string;
+    restored_history: boolean;
+}>;

package/dist/replace-connection.js

@@ -0,0 +1,77 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, rename, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { parse } from './artifacts.js';
+import { contextSchema, remoteId, bindingSchema } from './schema.js';
+import { fail } from './errors.js';
+import { CLI_NAME } from './brand.js';
+/** CLI-only, after the user confirms moving this folder to another help centre. The device credential is untouched. */
+export async function replaceConnection(bridge, expectedProjectId, projectId) {
+    parse(remoteId, projectId);
+    parse(remoteId, expectedProjectId);
+    const context = parse(contextSchema, await bridge.api.request('GET', `/projects/${projectId}/context`), 'invalid_response');
+    if (context.project.id !== projectId)
+        fail('invalid_response', 'Project identity mismatch.');
+    return bridge.lock(async () => {
+        const previous = await bridge.binding();
+        if (previous.project_id !== expectedProjectId)
+            fail('destination_mismatch', `The workspace connection changed during setup. Run ${CLI_NAME} init again to review it.`);
+        await bridge.runs.assertAvailable();
+        if ((await bridge.setup.progress())?.status === 'running')
+            fail('workspace_busy', 'Finish or stop project analysis before changing the connected help centre.');
+        const root = bridge.stateRoot;
+        const archive = `${root}/archives/project-${expectedProjectId}-${randomUUID()}`;
+        const candidates = [];
+        for (const entry of await bridge.ws.list(`${root}/archives`)) {
+            if (!entry.isDirectory() || !entry.name.startsWith(`project-${projectId}-`))
+                continue;
+            const saved = `${root}/archives/${entry.name}`;
+            if (!await bridge.ws.exists(`${saved}/binding.json`))
+                continue;
+            const identity = bindingSchema.safeParse(await bridge.ws.json(`${saved}/binding.json`));
+            if (identity.success && identity.data.project_id === projectId && identity.data.api_origin === bridge.api.origin) {
+                candidates.push({ root: saved, time: (await stat(await bridge.ws.resolve(saved))).mtimeMs });
+            }
+        }
+        const restore = candidates.sort((a, b) => b.time - a.time)[0]?.root;
+        // Detection and agent settings belong to the checkout. Its task directories
+        // contain the summary/overview referenced by the accepted analysis receipt.
+        // Working files already have project-specific paths; keep those paths stable
+        // so archived runs can be restored and resumed without moving their artifacts.
+        const entries = (await bridge.ws.list(root))
+            .filter(entry => !['operation.lock', 'dev', 'archives', 'setup', 'work'].includes(entry.name)).map(entry => entry.name);
+        entries.push(...(await bridge.ws.list(`${root}/setup`))
+            .filter(entry => !['analysis.json', 'settings.json', 'tasks'].includes(entry.name)).map(entry => `setup/${entry.name}`));
+        const moved = [];
+        const restored = [];
+        try {
+            for (const entry of entries) {
+                const destination = await bridge.ws.resolve(`${archive}/${entry}`);
+                await mkdir(path.dirname(destination), { recursive: true, mode: 0o700 });
+                await rename(await bridge.ws.resolve(`${root}/${entry}`), destination);
+                moved.push(entry);
+            }
+            if (restore)
+                for (const entry of ['runs', 'articles', 'bundles', 'previews', 'active-run.json']) {
+                    if (!await bridge.ws.exists(`${restore}/${entry}`))
+                        continue;
+                    await rename(await bridge.ws.resolve(`${restore}/${entry}`), await bridge.ws.resolve(`${root}/${entry}`));
+                    restored.push(entry);
+                }
+            await bridge.ws.writeJson(`${root}/binding.json`, { version: 1, api_origin: bridge.api.origin, project_id: projectId });
+            return { archive, restored_history: restored.length > 0 };
+        }
+        catch (error) {
+            for (const entry of restored.reverse())
+                await rename(await bridge.ws.resolve(`${root}/${entry}`), await bridge.ws.resolve(`${restore}/${entry}`));
+            // Restore only entries actually moved, including the previous binding.
+            for (const entry of moved.reverse()) {
+                await rm(await bridge.ws.resolve(`${root}/${entry}`), { recursive: true, force: true });
+                await rename(await bridge.ws.resolve(`${archive}/${entry}`), await bridge.ws.resolve(`${root}/${entry}`));
+            }
+            await rm(await bridge.ws.resolve(archive), { recursive: true, force: true });
+            throw error;
+        }
+    });
+}
+//# sourceMappingURL=replace-connection.js.map

package/dist/replace-connection.js.map

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

package/dist/repository-actions.d.ts

@@ -0,0 +1,18 @@
+import type { Bridge } from './bridge.js';
+export type RepositoryFeature = 'article_gaps' | 'video_walkthrough';
+/** Preserve the requested action through account, permission and repository setup. */
+export declare function repositoryAction(bridge: Bridge, action: 'find_article_gaps' | 'create_video_walkthrough' | 'connect_repository', feature?: RepositoryFeature): Promise<{
+    instructions: string;
+    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;
+    status: string;
+}>;

package/dist/repository-actions.js

@@ -0,0 +1,9 @@
+import { resolveAction } from './actions.js';
+/** Preserve the requested action through account, permission and repository setup. */
+export async function repositoryAction(bridge, action, feature = 'article_gaps') {
+    const requested = action === 'connect_repository' ? feature === 'video_walkthrough' ? 'create_video_walkthrough' : 'find_article_gaps' : action;
+    const decision = await resolveAction(bridge, requested);
+    return { status: decision.allowed ? 'available' : 'action_required', ...decision,
+        instructions: 'Show the action-specific next step and preserve the requested action. The user must approve browser consent. Retry the original action after setup; do not start local analysis or generation.' };
+}
+//# sourceMappingURL=repository-actions.js.map

package/dist/repository-actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository-actions.js","sourceRoot":"","sources":["../src/repository-actions.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,sFAAsF;AACtF,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,MAAc,EAAE,MAA+E,EAAE,UAA6B,cAAc;IACjL,MAAM,SAAS,GAAG,MAAM,KAAK,oBAAoB,CAAC,CAAC,CAAC,OAAO,KAAK,mBAAmB,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,MAAM,CAAC;IAChJ,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACxD,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,iBAAiB,EAAE,GAAG,QAAQ;QAC9E,YAAY,EAAE,gMAAgM,EAAE,CAAC;AACrN,CAAC"}

package/dist/repository-benefits.d.ts

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+import { repositoryConnectionSchema } from './schema.js';
+export declare const repositoryInvitationSchema: z.ZodObject<{
+    id: z.ZodString;
+    message: z.ZodString;
+    connect_url: z.ZodURL;
+}, z.core.$strip>;
+export type RepositoryInvitation = z.infer<typeof repositoryInvitationSchema>;
+export declare const repositoryBenefits: readonly [{
+    readonly id: "agent_allowance";
+    readonly category: "usage";
+    readonly message: "Keep your coding-agent allowance for building your product. Generate future articles using your SupportPages.io plan’s AI allowance.";
+}, {
+    readonly id: "documentation_allowance";
+    readonly category: "usage";
+    readonly message: "Let SupportPages.io spend its AI allowance on your documentation, while you keep your coding-agent usage for your product.";
+}, {
+    readonly id: "next_article_allowance";
+    readonly category: "usage";
+    readonly message: "Your next article can use your SupportPages.io plan’s AI allowance. Connect your repository to generate it in the web app.";
+}, {
+    readonly id: "elapsed_generation";
+    readonly category: "hosted";
+    readonly message: "This draft was ready in {duration}. Next time, let SupportPages.io handle generation without keeping your local coding agent running.";
+}, {
+    readonly id: "web_generation";
+    readonly category: "hosted";
+    readonly message: "Create your next article directly in SupportPages.io, without opening a local coding-agent session.";
+}, {
+    readonly id: "background_generation";
+    readonly category: "hosted";
+    readonly message: "Let SupportPages.io generate articles in the background while you carry on building your product.";
+}, {
+    readonly id: "topic_discovery";
+    readonly category: "discovery";
+    readonly message: "Not sure what to document next? SupportPages.io can suggest articles based on your product’s features.";
+}, {
+    readonly id: "coverage_gaps";
+    readonly category: "discovery";
+    readonly message: "Discover features your help centre doesn’t cover yet, with suggestions based on your repository.";
+}, {
+    readonly id: "section_suggestions";
+    readonly category: "organisation";
+    readonly message: "Give your help centre a clearer structure with section suggestions based on your product.";
+}, {
+    readonly id: "organisation";
+    readonly category: "organisation";
+    readonly message: "Help customers find the right answer by organising your articles into help-centre sections.";
+}, {
+    readonly id: "change_tracking";
+    readonly category: "maintenance";
+    readonly message: "Turn merged pull requests into suggestions for documentation your customers might need.";
+}, {
+    readonly id: "weekly_analysis";
+    readonly category: "maintenance";
+    readonly message: "Prefer a regular catch-up? Connect your repository and choose weekly analysis of merged pull requests.";
+}, {
+    readonly id: "maintenance";
+    readonly category: "maintenance";
+    readonly message: "Spot articles that need updating by comparing your documentation with your code.";
+}, {
+    readonly id: "automatic_drafts";
+    readonly category: "automation";
+    readonly message: "Choose automatic draft generation to turn article suggestions into drafts you can review before publishing.";
+}, {
+    readonly id: "batch_generation";
+    readonly category: "automation";
+    readonly message: "Work through your documentation backlog by generating multiple suggested articles from the web app.";
+}];
+/** The exact paragraph the agent shows after a draft review link: the benefit, then the link. */
+export declare const repositoryShowText: (invitation: RepositoryInvitation) => string;
+export declare function articleDuration(start?: string, ready?: string): string | undefined;
+/** Device-local preferences and deduplication, shared by all checkouts of a help centre. */
+export declare class RepositoryReminders {
+    private journal;
+    constructor(configDir?: string);
+    private transaction;
+    preference(origin: string, projectId: string, enabled?: boolean): Promise<{
+        enabled: boolean;
+        api_origin: string;
+        project_id: string;
+        scope: string;
+    }>;
+    complete(input: {
+        origin: string;
+        projectId: string;
+        articleId: string;
+        connection?: z.infer<typeof repositoryConnectionSchema>;
+        firstWriterStartedAt?: string;
+        readyAt?: string;
+    }): Promise<{
+        id: "maintenance" | "agent_allowance" | "documentation_allowance" | "next_article_allowance" | "elapsed_generation" | "web_generation" | "background_generation" | "topic_discovery" | "coverage_gaps" | "section_suggestions" | "organisation" | "change_tracking" | "weekly_analysis" | "automatic_drafts" | "batch_generation";
+        message: string;
+        connect_url: string;
+    } | undefined>;
+}