dsh-gh-pages-artifacts 0.1.0

package/lib/content.js

@@ -0,0 +1,142 @@
+/**
+ * Read one regular file that lies inside the Session working directory. Publishing makes data
+ * public, so this is stricter than the built-in read tool: symlinks, directories, and paths that
+ * resolve outside the workspace are refused.
+ * @param ctx - plugin context providing `fs`.
+ * @param exec - tool execution (Session working directory, cancellation).
+ * @param path - workspace-relative or absolute path.
+ * @param maxBytes - size ceiling.
+ * @returns the file bytes.
+ */
+export async function readWorkspaceFile(ctx, exec, path, maxBytes) {
+    if (path.trim() === '')
+        throw new Error('path must not be empty');
+    const fs = ctx.get('fs');
+    if (fs === undefined)
+        throw new Error('Publishing from a path needs the filesystem service, which this harness does not provide; pass the content inline instead');
+    const cwd = exec.agent?.session.header.cwd;
+    if (cwd === undefined)
+        throw new Error('Publishing from a path needs a Session workspace; pass the content inline instead');
+    const signal = exec.signal;
+    const entry = await fs.lstat(path, { cwd }, signal);
+    if (entry === undefined)
+        throw new Error(`${path} does not exist; write the file first or check the path`);
+    if (entry.type !== 'file')
+        throw new Error(`${path} is not a regular file (symlinks and directories are not published)`);
+    const root = await fs.resolve(cwd, { signal });
+    const target = await fs.resolve(path, { cwd, signal });
+    if (!fs.contains(root, target))
+        throw new Error(`${path} is outside the Session workspace; only files inside the workspace can be published`);
+    const info = await fs.stat(target, signal);
+    if (info === undefined || info.type !== 'file')
+        throw new Error(`${path} is not a regular file`);
+    if (info.size !== undefined && info.size > maxBytes) {
+        throw new Error(`${path} is ${formatBytes(info.size)}, above the ${formatBytes(maxBytes)} publish limit`);
+    }
+    return await fs.readBytes(target, signal, maxBytes);
+}
+/**
+ * The last path segment, used as the default asset name.
+ * @param path - workspace path.
+ */
+export function baseName(path) {
+    const parts = path.split(/[\\/]/).filter(part => part !== '');
+    return parts.at(-1) ?? path;
+}
+/** Extensions published as text and therefore screened for secrets. */
+const TEXT_EXTENSIONS = new Set([
+    'html', 'htm', 'md', 'markdown', 'txt', 'css', 'js', 'mjs', 'json', 'svg', 'xml', 'csv', 'tsv', 'yaml', 'yml', 'map',
+]);
+/**
+ * @param name - file name.
+ * @returns whether the name has a text extension.
+ */
+export function isTextName(name) {
+    const dot = name.lastIndexOf('.');
+    return dot >= 0 && TEXT_EXTENSIONS.has(name.slice(dot + 1).toLowerCase());
+}
+const SECRET_PATTERNS = [
+    { label: 'GitHub token', pattern: /\b(?:gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{60,})\b/ },
+    { label: 'private key', pattern: /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----/ },
+    { label: 'AWS access key id', pattern: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/ },
+    { label: 'AWS secret access key', pattern: /aws_secret_access_key\s*[:=]\s*['"]?[A-Za-z0-9/+=]{40}\b/i },
+    { label: 'Slack token', pattern: /\bxox[abposr]-[A-Za-z0-9-]{10,}\b/ },
+    { label: 'API secret key (sk-...)', pattern: /\bsk-(?:proj-|ant-)?[A-Za-z0-9_-]{32,}\b/ },
+    { label: 'Google API key', pattern: /\bAIza[0-9A-Za-z_-]{35}\b/ },
+    { label: 'Google OAuth token', pattern: /\b(?:ya29\.[0-9A-Za-z_-]{20,}|1\/\/0[0-9A-Za-z_-]{30,})/ },
+    { label: 'Stripe secret key', pattern: /\b(?:sk|rk)_live_[A-Za-z0-9]{20,}\b/ },
+    { label: 'npm token', pattern: /\bnpm_[A-Za-z0-9]{36}\b/ },
+    { label: 'GitLab token', pattern: /\bglpat-[A-Za-z0-9_-]{20,}\b/ },
+    { label: 'Hugging Face token', pattern: /\bhf_[A-Za-z0-9]{30,}\b/ },
+    { label: 'PyPI token', pattern: /\bpypi-[A-Za-z0-9_-]{50,}\b/ },
+    { label: 'JSON Web Token', pattern: /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/ },
+    { label: 'password in a URL', pattern: /\b[a-z][a-z0-9+.-]*:\/\/[^\s:/?#@'"<>]+:[^\s/?#@'"<>]{3,}@[^\s/?#'"<>]+/i },
+    {
+        label: 'password or secret assignment',
+        pattern: /\b(?:password|passwd|pwd|secret|client_secret|api[_-]?key|access[_-]?token|auth[_-]?token)\b["']?\s*[:=]\s*["']?(?=[^\s"'<>{}$]*\d)(?=[^\s"'<>{}$]*[A-Za-z])[^\s"'<>{}$]{12,}/i,
+    },
+];
+/**
+ * Find credential-like strings in text that is about to be published.
+ * @param text - content to screen.
+ * @param knownSecrets - exact secret values that must never appear (for example the token in use);
+ *   their base64, hex, and URL-encoded forms are checked too.
+ * @returns labels of the kinds found; empty when clean.
+ */
+export function findSecrets(text, knownSecrets = []) {
+    const found = new Set();
+    for (const secret of knownSecrets) {
+        if (secret.length < 8)
+            continue;
+        const forms = [
+            secret,
+            Buffer.from(secret).toString('base64').replace(/=+$/, ''),
+            Buffer.from(secret).toString('base64url'),
+            Buffer.from(secret).toString('hex'),
+            encodeURIComponent(secret),
+        ];
+        if (forms.some(form => text.includes(form)))
+            found.add('the GitHub token this plugin uses');
+    }
+    for (const { label, pattern } of SECRET_PATTERNS) {
+        if (pattern.test(text))
+            found.add(label);
+    }
+    return [...found];
+}
+const CREDENTIAL_NAMES = [
+    /^\.env(?:\..*)?$/i, /^\.envrc$/i, /^\.netrc$/i, /^_netrc$/i, /^\.npmrc$/i, /^\.pypirc$/i, /^\.git-credentials$/i,
+    /^\.pgpass$/i, /^\.htpasswd$/i, /^id_(?:rsa|dsa|ecdsa|ed25519)(?:\.pub)?$/i, /\.(?:pem|key|p12|pfx|jks|keystore|kdbx|gpg|asc|ovpn)$/i,
+    /^credentials(?:\.(?:json|ya?ml|toml|ini|env|csv))?$/i, /^secrets?\.(?:json|ya?ml|toml|ini|env)$/i, /^\.credentials\.ya?ml$/i, /^service[-_]?account.*\.json$/i,
+    /^application_default_credentials\.json$/i, /^kubeconfig$/i,
+];
+const CREDENTIAL_DIRS = new Set(['.ssh', '.aws', '.gnupg', '.dsh', '.git', '.kube', '.docker', '.config', '.azure', '.gcloud']);
+/**
+ * Check whether a workspace path looks like a credential file or a hidden file.
+ * @param path - workspace path as given.
+ * @returns a reason to refuse, or undefined when it looks like ordinary content.
+ */
+export function credentialPathProblem(path) {
+    const segments = path.split(/[\\/]/).filter(segment => segment !== '' && segment !== '.');
+    for (const segment of segments.slice(0, -1)) {
+        if (CREDENTIAL_DIRS.has(segment.toLowerCase()))
+            return `${path} is inside ${segment}/, which holds credentials or configuration`;
+    }
+    const name = segments.at(-1) ?? path;
+    if (CREDENTIAL_NAMES.some(pattern => pattern.test(name)))
+        return `${path} looks like a credential or key file`;
+    if (name.startsWith('.'))
+        return `${path} is a hidden file`;
+    return undefined;
+}
+/**
+ * @param bytes - byte count.
+ * @returns a short human size.
+ */
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KiB`;
+    return `${(bytes / 1024 / 1024).toFixed(1)} MiB`;
+}

package/lib/github.d.ts

@@ -0,0 +1,78 @@
+/** Minimal GitHub REST client: JSON requests, bounded retries, rate-limit handling, token scrubbing. */
+/** Options for one {@link GitHubClient}. */
+export interface GitHubClientOptions {
+    /** API base URL without trailing slash, e.g. https://api.github.com. */
+    readonly apiBaseUrl: string;
+    /** Bearer token. Never logged, never placed in errors. */
+    readonly token: string;
+    /** User-Agent header; GitHub rejects requests without one. */
+    readonly userAgent: string;
+    /** Fetch implementation; defaults to the global fetch (which honours the harness proxy). */
+    readonly fetch?: typeof fetch;
+    /** Per-request timeout in milliseconds. */
+    readonly requestTimeoutMs?: number;
+    /** Retries for transient failures (network errors, 5xx, rate limits). */
+    readonly maxRetries?: number;
+    /** Longest wait the client accepts for a rate-limit reset before failing. */
+    readonly maxRateLimitWaitMs?: number;
+    /** Sleep implementation, replaceable in tests. */
+    readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/** Per-request options. */
+export interface RequestOptions {
+    /** JSON body. */
+    readonly body?: unknown;
+    /** Statuses returned to the caller instead of thrown. */
+    readonly allowStatus?: readonly number[];
+    /** Whether transient failures may be retried; false for non-idempotent writes. */
+    readonly retry?: boolean;
+    /** Caller cancellation. */
+    readonly signal?: AbortSignal | undefined;
+}
+/** A completed response. */
+export interface GitHubResponse<T> {
+    readonly status: number;
+    readonly data: T;
+    readonly headers: Headers;
+}
+/** A GitHub API error with the HTTP status and GitHub's message. */
+export declare class GitHubApiError extends Error {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    readonly apiMessage: string;
+    readonly acceptedPermissions?: string | undefined;
+    readonly name = "GitHubApiError";
+    constructor(status: number, method: string, path: string, apiMessage: string, acceptedPermissions?: string | undefined);
+}
+/** Thin JSON client for the GitHub REST API. */
+export declare class GitHubClient {
+    private readonly options;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly maxRateLimitWaitMs;
+    private readonly sleep;
+    constructor(options: GitHubClientOptions);
+    /**
+     * Send one request.
+     * @param method - HTTP method.
+     * @param path - path beginning with '/', relative to the API base URL.
+     * @param options - body, allowed statuses, retry policy, cancellation.
+     * @returns the parsed response.
+     * @throws GitHubApiError for statuses outside 2xx and `allowStatus`.
+     */
+    request<T = unknown>(method: string, path: string, options?: RequestOptions): Promise<GitHubResponse<T>>;
+    private send;
+    /**
+     * Remove the token from text that may reach the model or logs.
+     * @param text - text to clean.
+     * @returns the text with every token occurrence replaced.
+     */
+    scrub(text: string): string;
+}
+/**
+ * Encode each segment of a repository path for use in a URL.
+ * @param path - slash-separated path.
+ */
+export declare function encodePath(path: string): string;

package/lib/github.js

@@ -0,0 +1,190 @@
+/** Minimal GitHub REST client: JSON requests, bounded retries, rate-limit handling, token scrubbing. */
+/** A GitHub API error with the HTTP status and GitHub's message. */
+export class GitHubApiError extends Error {
+    status;
+    method;
+    path;
+    apiMessage;
+    acceptedPermissions;
+    name = 'GitHubApiError';
+    constructor(status, method, path, apiMessage, acceptedPermissions) {
+        super(`GitHub API ${method} ${path} failed with ${status}: ${apiMessage}`);
+        this.status = status;
+        this.method = method;
+        this.path = path;
+        this.apiMessage = apiMessage;
+        this.acceptedPermissions = acceptedPermissions;
+    }
+}
+const API_VERSION = '2022-11-28';
+/** Thin JSON client for the GitHub REST API. */
+export class GitHubClient {
+    options;
+    fetchImpl;
+    timeoutMs;
+    maxRetries;
+    maxRateLimitWaitMs;
+    sleep;
+    constructor(options) {
+        this.options = options;
+        this.fetchImpl = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+        this.timeoutMs = options.requestTimeoutMs ?? 30_000;
+        this.maxRetries = options.maxRetries ?? 3;
+        this.maxRateLimitWaitMs = options.maxRateLimitWaitMs ?? 60_000;
+        this.sleep = options.sleep ?? abortableSleep;
+    }
+    /**
+     * Send one request.
+     * @param method - HTTP method.
+     * @param path - path beginning with '/', relative to the API base URL.
+     * @param options - body, allowed statuses, retry policy, cancellation.
+     * @returns the parsed response.
+     * @throws GitHubApiError for statuses outside 2xx and `allowStatus`.
+     */
+    async request(method, path, options = {}) {
+        const retry = options.retry ?? true;
+        let attempt = 0;
+        for (;;) {
+            options.signal?.throwIfAborted();
+            let response;
+            try {
+                response = await this.send(method, path, options);
+            }
+            catch (error) {
+                if (options.signal?.aborted === true)
+                    throw options.signal.reason;
+                if (retry && attempt < this.maxRetries) {
+                    await this.sleep(backoff(attempt++), options.signal);
+                    continue;
+                }
+                throw new Error(this.scrub(`GitHub API ${method} ${path} could not be reached: ${describeError(error)}`));
+            }
+            const status = response.status;
+            if (status >= 200 && status < 300 || options.allowStatus?.includes(status) === true) {
+                return { status, data: await readBody(response), headers: response.headers };
+            }
+            const body = await readBody(response).catch(() => undefined);
+            const apiMessage = this.scrub(messageOf(body) ?? response.statusText ?? 'request failed');
+            const rateWait = rateLimitWait(response, apiMessage);
+            if (rateWait !== undefined) {
+                if (rateWait <= this.maxRateLimitWaitMs && attempt < this.maxRetries) {
+                    attempt++;
+                    await this.sleep(rateWait, options.signal);
+                    continue;
+                }
+                throw new GitHubApiError(status, method, path, `${apiMessage} (GitHub rate limit; retry in about ${Math.ceil(rateWait / 1000)} s)`);
+            }
+            if (status >= 500 && retry && attempt < this.maxRetries) {
+                await this.sleep(backoff(attempt++), options.signal);
+                continue;
+            }
+            throw new GitHubApiError(status, method, path, apiMessage, response.headers.get('x-accepted-github-permissions') ?? undefined);
+        }
+    }
+    async send(method, path, options) {
+        const timeout = AbortSignal.timeout(this.timeoutMs);
+        const signal = options.signal === undefined ? timeout : AbortSignal.any([options.signal, timeout]);
+        const headers = {
+            'Accept': 'application/vnd.github+json',
+            'Authorization': `Bearer ${this.options.token}`,
+            'User-Agent': this.options.userAgent,
+            'X-GitHub-Api-Version': API_VERSION,
+        };
+        const init = { method, headers, signal, redirect: 'follow' };
+        if (options.body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            init.body = JSON.stringify(options.body);
+        }
+        return await this.fetchImpl(`${this.options.apiBaseUrl}${path}`, init);
+    }
+    /**
+     * Remove the token from text that may reach the model or logs.
+     * @param text - text to clean.
+     * @returns the text with every token occurrence replaced.
+     */
+    scrub(text) {
+        const token = this.options.token;
+        return token.length >= 8 ? text.split(token).join('***') : text;
+    }
+}
+async function readBody(response) {
+    if (response.status === 204 || response.status === 205)
+        return undefined;
+    const text = await response.text();
+    if (text === '')
+        return undefined;
+    const type = response.headers.get('content-type') ?? '';
+    if (type.includes('json'))
+        return JSON.parse(text);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function messageOf(body) {
+    if (typeof body === 'string')
+        return body.slice(0, 300);
+    if (typeof body !== 'object' || body === null)
+        return undefined;
+    const record = body;
+    const message = typeof record.message === 'string' ? record.message : undefined;
+    const details = Array.isArray(record.errors)
+        ? record.errors.map(item => typeof item === 'string' ? item : item.message)
+            .filter((item) => typeof item === 'string')
+        : [];
+    return details.length > 0 ? `${message ?? 'error'} (${details.join('; ')})` : message;
+}
+/**
+ * Milliseconds to wait before retrying a rate-limited response, or undefined when it is not one.
+ * @param response - the failed response.
+ * @param message - GitHub's message.
+ */
+function rateLimitWait(response, message) {
+    const status = response.status;
+    if (status !== 403 && status !== 429)
+        return undefined;
+    const retryAfter = response.headers.get('retry-after');
+    if (retryAfter !== null && /^\d+$/.test(retryAfter))
+        return Number(retryAfter) * 1000;
+    const remaining = response.headers.get('x-ratelimit-remaining');
+    const reset = response.headers.get('x-ratelimit-reset');
+    if (remaining === '0' && reset !== null && /^\d+$/.test(reset)) {
+        return Math.max(1000, Number(reset) * 1000 - Date.now());
+    }
+    if (status === 429 || /secondary rate limit|abuse/i.test(message))
+        return 60_000;
+    return undefined;
+}
+function backoff(attempt) {
+    return Math.min(8000, 500 * 2 ** attempt) + Math.floor(Math.random() * 250);
+}
+function describeError(error) {
+    if (error instanceof Error) {
+        const cause = error.cause;
+        return cause instanceof Error ? `${error.message} (${cause.message})` : error.message;
+    }
+    return String(error);
+}
+async function abortableSleep(ms, signal) {
+    signal?.throwIfAborted();
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * Encode each segment of a repository path for use in a URL.
+ * @param path - slash-separated path.
+ */
+export function encodePath(path) {
+    return path.split('/').map(encodeURIComponent).join('/');
+}

package/lib/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * DeepSeek Harness plugin that lets agents publish HTML pages and Markdown documents as
+ * shareable artifacts on GitHub Pages.
+ * @module dsh-gh-pages-artifacts
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { Config } from './config.js';
+export { Config };
+export type { ApprovalMode, RepoStrategy, SubagentAccess, Settings } from './config.js';
+export { ArtifactsRuntime, VERSION } from './service.js';
+export type { RuntimeHooks } from './service.js';
+export { ALL_TOOLS, MUTATING_TOOLS, PUBLISH_TOOL, LIST_TOOL, READ_TOOL, DELETE_TOOL, STATUS_TOOL, REPOSITORY_TOOL } from './tools.js';
+/** Loader identity. */
+export declare const name = "gh-pages-artifacts";
+/** Required services; the skill registry, system prompt, credentials, and approval are optional. */
+export declare const inject: string[];
+/**
+ * Register the artifact tools, their visibility rules, prompt guidance, and the bundled skill.
+ * @param ctx - host plugin context.
+ * @param config - validated configuration.
+ */
+export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -0,0 +1,48 @@
+import { Config, normalizeConfig } from './config.js';
+import { registerPrompt } from './prompt.js';
+import { ArtifactsRuntime } from './service.js';
+import { registerSkill } from './skill.js';
+import { ALL_TOOLS, createTools, MUTATING_TOOLS } from './tools.js';
+import { installVisibility } from './visibility.js';
+import { installWebRoutes } from './web-routes.js';
+export { Config };
+export { ArtifactsRuntime, VERSION } from './service.js';
+export { ALL_TOOLS, MUTATING_TOOLS, PUBLISH_TOOL, LIST_TOOL, READ_TOOL, DELETE_TOOL, STATUS_TOOL, REPOSITORY_TOOL } from './tools.js';
+/** Loader identity. */
+export const name = 'gh-pages-artifacts';
+/** Required services; the skill registry, system prompt, credentials, and approval are optional. */
+export const inject = ['tools'];
+/**
+ * Register the artifact tools, their visibility rules, prompt guidance, and the bundled skill.
+ * @param ctx - host plugin context.
+ * @param config - validated configuration.
+ */
+export function apply(ctx, config) {
+    // Validate once up front; volatile options (edited on the settings page) are re-read per operation.
+    const settings = normalizeConfig(config);
+    // The entry id names this row's settings namespace, which artifact_repository writes to.
+    const entryId = ctx.fiber.entry?.options?.id;
+    const runtime = new ArtifactsRuntime(ctx, () => normalizeConfig(config), {}, typeof entryId === 'string' ? entryId : undefined);
+    for (const tool of createTools(runtime))
+        ctx.tools.register(tool);
+    // The sidebar's Artifacts panel reads the list through these routes (web and desktop only).
+    installWebRoutes(ctx, runtime);
+    installVisibility(ctx, {
+        allTools: ALL_TOOLS,
+        mutatingTools: MUTATING_TOOLS,
+        hideFromPresets: settings.hideFromPresets,
+        subagentAccess: settings.subagentAccess,
+    });
+    if (settings.promptGuidance)
+        ctx.inject(['systemPrompt'], promptCtx => registerPrompt(promptCtx, settings.bundledSkill));
+    if (settings.bundledSkill) {
+        ctx.inject(['skills'], async (skillsCtx) => {
+            try {
+                await registerSkill(skillsCtx);
+            }
+            catch (error) {
+                skillsCtx.logger.warn(`gh-pages-artifacts: bundled skill unavailable: ${String(error)}`);
+            }
+        });
+    }
+}

package/lib/manifest.d.ts

@@ -0,0 +1,88 @@
+/** Artifact manifest stored on the Pages branch, plus id and asset-name rules. */
+/** Repository-root path of the manifest. It sits outside the artifact folders. */
+export declare const MANIFEST_PATH = ".dsh-artifacts.json";
+/** Kinds of artifact the plugin publishes. */
+export type ArtifactKind = 'html' | 'markdown';
+/** One published artifact. */
+export interface ArtifactRecord {
+    /** Stable id; the URL path segment. Never changes. */
+    id: string;
+    /** Human title; may change without moving the URL. */
+    title: string;
+    /** Page kind. */
+    kind: ArtifactKind;
+    /** Optional one-line summary. */
+    description?: string;
+    /** ISO timestamp of the first publish. */
+    createdAt: string;
+    /** ISO timestamp of the latest publish. */
+    updatedAt: string;
+    /** Revision, starting at 1 and incremented by every update. */
+    rev: number;
+    /** Files published in the artifact folder, relative to it, sorted. */
+    files: string[];
+}
+/** Manifest file shape. */
+export interface Manifest {
+    version: 1;
+    artifacts: Record<string, ArtifactRecord>;
+    /** Deleted ids, never reused, so an old link cannot show different content. */
+    tombstones: string[];
+}
+/** File holding the served page. */
+export declare const PAGE_FILE = "index.html";
+/** File holding the Markdown source of a markdown artifact. */
+export declare const SOURCE_FILE = "source.md";
+/** Valid artifact id: lowercase letters, digits, and inner hyphens, 1-64 characters. */
+export declare const ID_PATTERN: RegExp;
+/** Ids that would collide with site-level files or common folders. */
+export declare const RESERVED_IDS: ReadonlySet<string>;
+/** Error for a manifest that cannot be read safely. */
+export declare class ManifestError extends Error {
+    readonly name = "ManifestError";
+}
+/** @returns an empty manifest. */
+export declare function emptyManifest(): Manifest;
+/**
+ * Parse and validate manifest text. A malformed manifest is never overwritten silently.
+ * @param text - file content.
+ * @returns the manifest.
+ * @throws ManifestError when the content is not a version-1 manifest.
+ */
+export declare function parseManifest(text: string): Manifest;
+/**
+ * Serialize a manifest deterministically so diffs stay readable.
+ * @param manifest - manifest to write.
+ * @returns JSON text with a trailing newline.
+ */
+export declare function serializeManifest(manifest: Manifest): string;
+/**
+ * Turn a title into a URL slug: lowercase ASCII letters and digits joined by hyphens.
+ * @param title - free text.
+ * @param maxLength - longest result.
+ * @returns the slug, or 'artifact' when nothing usable remains.
+ */
+export declare function slugify(title: string, maxLength?: number): string;
+/**
+ * Build a fresh id from a title plus a random suffix, so URLs are readable but not guessable.
+ * @param title - artifact title.
+ * @param suffix - random lowercase base32 text.
+ */
+export declare function idFromTitle(title: string, suffix: string): string;
+/**
+ * Check a caller-chosen id.
+ * @param id - candidate id.
+ * @returns an error message, or undefined when valid.
+ */
+export declare function idProblem(id: string): string | undefined;
+/**
+ * Check an asset name, the path of an extra file relative to the artifact folder.
+ * @param name - candidate name such as `chart.png` or `img/logo.svg`.
+ * @returns an error message, or undefined when valid.
+ */
+export declare function assetNameProblem(name: string): string | undefined;
+/**
+ * @param path - candidate relative path.
+ * @returns whether it is 1-4 safe segments with no dot-segments.
+ */
+export declare function isSafeRelativePath(path: string): boolean;