dsh-gh-pages-artifacts 0.1.0

package/lib/approval.js

@@ -0,0 +1,59 @@
+/**
+ * Ask the user before a publish, update, or delete, following the configured mode. With
+ * 'unless-full-access' the prompt is skipped only in sessions that run with the danger-full-access
+ * sandbox and never prompt for approval (the "Full access" preset). The gate runs
+ * inside the tool body, after arguments and the target URL are known, so the prompt names the
+ * exact URL. Only an explicit 'allowed-once' lets the change through.
+ * @param ctx - plugin context.
+ * @param mode - configured approval mode.
+ * @param exec - tool execution.
+ * @param ask - request text.
+ * @throws Error with a model-facing explanation when approval is not granted.
+ */
+export async function requireApproval(ctx, mode, exec, ask) {
+    if (mode === 'off')
+        return;
+    const agent = exec.agent;
+    const approval = ctx.get('approval');
+    const policy = approval === undefined || agent === undefined
+        ? undefined
+        : approval.overrideOf(agent.session) ?? approval.config.policy ?? 'ask';
+    if (mode === 'unless-full-access') {
+        // Full access means the danger-full-access sandbox *and* no approval prompts, the way the
+        // shipped "Full access" preset is defined. Auto mode keeps prompting, so it is asked here too.
+        const sandbox = ctx.get('sandboxPolicy')?.resolve(agent === undefined ? {} : { session: agent.session });
+        if (sandbox?.mode === 'danger-full-access' && (policy === undefined || policy === 'never'))
+            return;
+    }
+    if (approval === undefined || agent === undefined || policy === undefined) {
+        throw new Error(`${ask.toolName} needs the user's approval, but this harness has no approval channel. `
+            + 'Ask the user to publish from an interactive session, or to set the plugin option approval: off.');
+    }
+    if (policy === 'never') {
+        const delegated = (agent.session.header.delegationDepth ?? 0) > 0;
+        throw new Error(delegated
+            ? `${ask.toolName} needs the user's approval, which a delegated subagent cannot request. Return the content to the parent agent so it can publish.`
+            : `${ask.toolName} needs the user's approval, but this session rejects approval requests automatically. Ask the user to change the permission mode, then retry.`);
+    }
+    const outcome = await approval.request({
+        agent,
+        toolName: ask.toolName,
+        callId: exec.callId,
+        reason: ask.reason,
+        displayReason: { en: ask.display },
+        signal: exec.signal,
+    });
+    switch (outcome) {
+        case 'allowed-once':
+            exec.signal.throwIfAborted();
+            return;
+        case 'rejected':
+            throw new Error(`The user declined: ${ask.reason}. Do not retry unless the user asks again.`);
+        case 'cancelled':
+            throw new Error(`The approval request was cancelled: ${ask.reason}`);
+        case 'unavailable':
+            throw new Error(`${ask.toolName} needs the user's approval, but no approval channel is available right now (for example a headless run).`);
+        default:
+            throw new Error(`${ask.toolName} was not approved`);
+    }
+}

package/lib/config.d.ts

@@ -0,0 +1,204 @@
+import z from '@deepseek-ai/schemastery';
+/** How publishing, updating, and deleting artifacts is approved. */
+export type ApprovalMode = 'unless-full-access' | 'always' | 'off';
+/** Which artifact tools delegated subagents may see. */
+export type SubagentAccess = 'read-only' | 'full' | 'none';
+/**
+ * Where new artifacts go: 'shared' puts every artifact in its own folder of one linked repository;
+ * 'per-artifact' creates a new repository (and Pages site) for each new artifact.
+ */
+export type RepoStrategy = 'shared' | 'per-artifact';
+/** A GitHub repository. */
+export interface RepoRef {
+    readonly owner: string;
+    readonly repo: string;
+}
+/** Raw plugin configuration as validated by {@link Config}. */
+export interface Config {
+    /** GitHub user or organization that owns the Pages repository. Defaults to the token's user. */
+    owner?: string | undefined;
+    /** Repository that hosts the artifacts. */
+    repo: string;
+    /** The shared repository as `owner/name` or a remote URL; overrides owner and repo for the shared repository. */
+    repository?: string | undefined;
+    /** Whether new artifacts share one repository or each get a new one. */
+    repoStrategy: RepoStrategy;
+    /** Name prefix of repositories created by the per-artifact strategy. */
+    repoPrefix: string;
+    /** Visibility of repositories created by the per-artifact strategy. */
+    repoVisibility: 'public' | 'private';
+    /** Folder for the local registry of published artifacts; defaults to $DSH_HOME/gh-pages-artifacts. */
+    registryDir?: string | undefined;
+    /** Branch GitHub Pages publishes from. */
+    branch: string;
+    /** Pages source folder inside the branch: '' for the root or 'docs'. */
+    siteDir: '' | 'docs';
+    /** Folder under the site root that holds artifacts; '' places them at the site root. */
+    pathPrefix: string;
+    /** Public base URL of the site, for custom domains. Discovered from the Pages API when unset. */
+    baseUrl?: string | undefined;
+    /** Name of the credential reference (environment variable) holding the GitHub token. */
+    tokenEnv: string;
+    /** GitHub REST API base URL; change it only for GitHub Enterprise Server. */
+    apiBaseUrl: string;
+    /** When publish, update, and delete ask the user first. */
+    approval: ApprovalMode;
+    /** Agent presets (modes) that never see the artifact tools. */
+    hideFromPresets: string[];
+    /** Which artifact tools delegated subagents see. */
+    subagentAccess: SubagentAccess;
+    /** Add `<meta name="robots" content="noindex, nofollow">` to published pages. */
+    noindex: boolean;
+    /** Content-Security-Policy injected as a meta tag; '' disables injection. */
+    csp: string;
+    /** Refuse to publish text that looks like a credential (tokens, private keys). */
+    blockSecrets: boolean;
+    /** Maximum total bytes of one publish (page plus assets). */
+    maxPublishBytes: number;
+    /** Optional author and committer identity for commits; defaults to the token's user. */
+    commitAuthor?: {
+        name?: string | undefined;
+        email?: string | undefined;
+    } | undefined;
+    /** Add a short system-prompt section describing the artifact tools. */
+    promptGuidance: boolean;
+    /** Register the bundled `artifact-pages` design skill. */
+    bundledSkill: boolean;
+}
+/** Schema validated by Cordis before `apply`. */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    owner: z<string, string, "volatile">;
+    repo: z<string, string, "volatile-defined">;
+    repository: z<string, string, "volatile">;
+    repoStrategy: z<"shared" | "per-artifact", "shared" | "per-artifact", "volatile-defined">;
+    repoPrefix: z<string, string, "volatile-defined">;
+    repoVisibility: z<"public" | "private", "public" | "private", "volatile-defined">;
+    registryDir: z<string, string, "plain">;
+    branch: z<string, string, "volatile-defined">;
+    siteDir: z<"" | "docs", "" | "docs", "defined">;
+    pathPrefix: z<string, string, "defined">;
+    baseUrl: z<string, string, "volatile">;
+    tokenEnv: z<string, string, "volatile-defined">;
+    apiBaseUrl: z<string, string, "defined">;
+    approval: z<"unless-full-access" | "always" | "off", "unless-full-access" | "always" | "off", "volatile-defined">;
+    hideFromPresets: z<string[], string[], "defined">;
+    subagentAccess: z<"read-only" | "full" | "none", "read-only" | "full" | "none", "defined">;
+    noindex: z<boolean, boolean, "volatile-defined">;
+    csp: z<string, string, "defined">;
+    blockSecrets: z<boolean, boolean, "volatile-defined">;
+    maxPublishBytes: z<number, number, "volatile-defined">;
+    commitAuthor: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+        name: z<string, string, "plain">;
+        email: z<string, string, "plain">;
+    }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+        name: z<string, string, "plain">;
+        email: z<string, string, "plain">;
+    }>>>, "volatile">;
+    promptGuidance: z<boolean, boolean, "defined">;
+    bundledSkill: z<boolean, boolean, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    owner: z<string, string, "volatile">;
+    repo: z<string, string, "volatile-defined">;
+    repository: z<string, string, "volatile">;
+    repoStrategy: z<"shared" | "per-artifact", "shared" | "per-artifact", "volatile-defined">;
+    repoPrefix: z<string, string, "volatile-defined">;
+    repoVisibility: z<"public" | "private", "public" | "private", "volatile-defined">;
+    registryDir: z<string, string, "plain">;
+    branch: z<string, string, "volatile-defined">;
+    siteDir: z<"" | "docs", "" | "docs", "defined">;
+    pathPrefix: z<string, string, "defined">;
+    baseUrl: z<string, string, "volatile">;
+    tokenEnv: z<string, string, "volatile-defined">;
+    apiBaseUrl: z<string, string, "defined">;
+    approval: z<"unless-full-access" | "always" | "off", "unless-full-access" | "always" | "off", "volatile-defined">;
+    hideFromPresets: z<string[], string[], "defined">;
+    subagentAccess: z<"read-only" | "full" | "none", "read-only" | "full" | "none", "defined">;
+    noindex: z<boolean, boolean, "volatile-defined">;
+    csp: z<string, string, "defined">;
+    blockSecrets: z<boolean, boolean, "volatile-defined">;
+    maxPublishBytes: z<number, number, "volatile-defined">;
+    commitAuthor: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+        name: z<string, string, "plain">;
+        email: z<string, string, "plain">;
+    }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+        name: z<string, string, "plain">;
+        email: z<string, string, "plain">;
+    }>>>, "volatile">;
+    promptGuidance: z<boolean, boolean, "defined">;
+    bundledSkill: z<boolean, boolean, "defined">;
+}>>, "plain">;
+/** Config as the Loader passes it: fields declared `.volatile()` arrive as live references. */
+export type LiveConfig = {
+    [K in keyof Config]: Config[K] | {
+        get(): Config[K];
+    };
+};
+/**
+ * Read the current values of a live config; volatile fields can change while the plugin runs
+ * (for example from its settings page), so callers read them per operation.
+ * @param config - config as passed to `apply`.
+ * @returns plain values.
+ */
+export declare function unwrapConfig(config: Config | LiveConfig): Config;
+/** Validated, normalized settings shared by every module. */
+export interface Settings {
+    readonly owner: string | undefined;
+    readonly repo: string;
+    /** Shared repository parsed from `repository`, when set. */
+    readonly repository: RepoRef | undefined;
+    readonly repoStrategy: RepoStrategy;
+    readonly repoPrefix: string;
+    readonly repoVisibility: 'public' | 'private';
+    readonly registryDir: string;
+    readonly branch: string;
+    readonly siteDir: string;
+    readonly pathPrefix: string;
+    readonly baseUrl: string | undefined;
+    readonly tokenEnv: string;
+    readonly apiBaseUrl: string;
+    readonly approval: ApprovalMode;
+    readonly hideFromPresets: readonly string[];
+    readonly subagentAccess: SubagentAccess;
+    readonly noindex: boolean;
+    readonly csp: string;
+    readonly blockSecrets: boolean;
+    readonly maxPublishBytes: number;
+    readonly commitAuthor: {
+        readonly name: string;
+        readonly email: string;
+    } | undefined;
+    readonly promptGuidance: boolean;
+    readonly bundledSkill: boolean;
+}
+/**
+ * Check the cross-field rules the schema cannot express and normalize paths and URLs.
+ * @param config - schema-validated configuration.
+ * @returns normalized settings.
+ * @throws Error naming the offending option.
+ */
+export declare function normalizeConfig(input: Config | LiveConfig): Settings;
+/**
+ * Parse a repository reference: `owner/name`, `https://<host>/owner/name(.git)`,
+ * `git@<host>:owner/name(.git)`, or `ssh://git@<host>/owner/name(.git)`. The host must be
+ * github.com, or the GitHub Enterprise host behind `apiBaseUrl`.
+ * @param input - user text.
+ * @param apiBaseUrl - normalized API base URL.
+ * @returns owner and repository name.
+ * @throws Error explaining the accepted forms.
+ */
+export declare function parseRepository(input: string, apiBaseUrl: string): RepoRef;
+/**
+ * Normalize a relative directory option such as `a` or `pages/a` to slash-joined safe segments.
+ * @param value - raw option value.
+ * @param option - option name for error messages.
+ * @returns the normalized path, '' for the root.
+ */
+export declare function normalizeRelativeDir(value: string, option: string): string;
+/**
+ * Validate an http(s) URL option and strip its trailing slash.
+ * @param value - raw option value.
+ * @param option - option name for error messages.
+ * @param carriesToken - whether the token is sent to this URL, which then must be HTTPS unless loopback.
+ * @returns the URL without a trailing slash.
+ */
+export declare function normalizeUrl(value: string, option: string, carriesToken: boolean): string;

package/lib/config.js

@@ -0,0 +1,241 @@
+/** Plugin configuration schema and the normalized settings the runtime reads. */
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import z from '@deepseek-ai/schemastery';
+const OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
+const REPO_PATTERN = /^[A-Za-z0-9._-]{1,100}$/;
+const BRANCH_PATTERN = /^(?!\/)(?!.*\/\/)(?!.*\.\.)(?!.*@\{)(?!.*\/$)(?!.*\.lock$)[A-Za-z0-9._\/-]{1,200}$/;
+const SEGMENT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** Schema validated by Cordis before `apply`. */
+export const Config = z.object({
+    owner: z.string().pattern(OWNER_PATTERN)
+        .description('GitHub user or organization owning the Pages repository. Defaults to the user the token belongs to.').volatile(),
+    repo: z.string().pattern(REPO_PATTERN).default('dsh-artifacts')
+        .description('Repository that hosts the artifacts. Use a dedicated repository, never your <owner>.github.io site.').volatile(),
+    repository: z.string()
+        .description('Shared repository as owner/name or a remote URL (https://github.com/owner/name.git or git@github.com:owner/name.git). Overrides owner and repo for the shared repository.').volatile(),
+    repoStrategy: z.union(['shared', 'per-artifact']).default('shared')
+        .description('shared: every artifact gets a folder in one repository; per-artifact: each new artifact gets its own new repository and Pages site.').volatile(),
+    repoPrefix: z.string().pattern(/^[A-Za-z0-9._-]{0,40}$/).default('artifact-')
+        .description('Name prefix of repositories the per-artifact strategy creates.').volatile(),
+    repoVisibility: z.union(['public', 'private']).default('public')
+        .description('Visibility of repositories the per-artifact strategy creates. Pages on private repositories needs a paid plan; the pages are public either way.').volatile(),
+    registryDir: z.string()
+        .description('Folder for the local registry and index page of published artifacts. Defaults to $DSH_HOME/gh-pages-artifacts.'),
+    branch: z.string().pattern(BRANCH_PATTERN).default('gh-pages')
+        .description('Branch GitHub Pages publishes from. It is created on first publish when missing.').volatile(),
+    siteDir: z.union(['', 'docs']).default('')
+        .description("Pages source folder: '' for the branch root or 'docs'."),
+    pathPrefix: z.string().default('')
+        .description("Folder under the site root that holds artifacts, for example 'a'. '' puts each artifact at <site>/<id>/."),
+    baseUrl: z.string()
+        .description('Public site URL, e.g. https://pages.example.com. Discovered from the Pages API when unset.').volatile(),
+    tokenEnv: z.string().role('credential-ref').default('GH_PAGES_TOKEN')
+        .description('Credential reference (environment variable name) holding a GitHub token with Contents read/write on the repository.').volatile(),
+    apiBaseUrl: z.string().default('https://api.github.com')
+        .description('GitHub REST API base URL. Change it only for GitHub Enterprise Server.'),
+    approval: z.union(['unless-full-access', 'always', 'off']).default('unless-full-access')
+        .description('unless-full-access: ask unless the session runs with danger-full-access; always: ask every time; off: never ask.').volatile(),
+    hideFromPresets: z.array(z.string()).default(['minimal'])
+        .description('Agent presets (modes) that never see the artifact tools.'),
+    subagentAccess: z.union(['read-only', 'full', 'none']).default('read-only')
+        .description('read-only: subagents may list and read but not publish or delete; full: all tools; none: no artifact tools.'),
+    noindex: z.boolean().default(true)
+        .description('Ask search engines not to index published pages.').volatile(),
+    csp: z.string().default("object-src 'none'; base-uri 'none'")
+        .description("Content-Security-Policy meta tag injected into every page. '' disables it."),
+    blockSecrets: z.boolean().default(true)
+        .description('Refuse to publish text that looks like a credential.').volatile(),
+    maxPublishBytes: z.natural().min(1024).default(10 * 1024 * 1024)
+        .description('Maximum total bytes of one publish, page plus assets.').volatile(),
+    commitAuthor: z.object({
+        name: z.string().description('Author name.'),
+        email: z.string().description('Author email.'),
+    }).description('Commit author and committer (both name and email). Defaults to the token user.').volatile(),
+    promptGuidance: z.boolean().default(true)
+        .description('Add a short system-prompt section that explains the artifact tools.'),
+    bundledSkill: z.boolean().default(true)
+        .description('Register the bundled artifact-pages design skill.'),
+});
+/**
+ * Read the current values of a live config; volatile fields can change while the plugin runs
+ * (for example from its settings page), so callers read them per operation.
+ * @param config - config as passed to `apply`.
+ * @returns plain values.
+ */
+export function unwrapConfig(config) {
+    const plain = {};
+    for (const [key, value] of Object.entries(config)) {
+        plain[key] = typeof value === 'object' && value !== null && typeof value.get === 'function'
+            ? value.get()
+            : value;
+    }
+    return plain;
+}
+/**
+ * Check the cross-field rules the schema cannot express and normalize paths and URLs.
+ * @param config - schema-validated configuration.
+ * @returns normalized settings.
+ * @throws Error naming the offending option.
+ */
+export function normalizeConfig(input) {
+    const config = unwrapConfig(input);
+    const pathPrefix = normalizeRelativeDir(config.pathPrefix, 'pathPrefix');
+    const apiBaseUrl = normalizeUrl(config.apiBaseUrl, 'apiBaseUrl', true);
+    const baseUrl = config.baseUrl === undefined || config.baseUrl.trim() === ''
+        ? undefined
+        : normalizeUrl(config.baseUrl, 'baseUrl', false);
+    if (/[\s;]/.test(config.tokenEnv) || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(config.tokenEnv)) {
+        throw new Error(`gh-pages-artifacts: tokenEnv must be an environment variable name, got "${config.tokenEnv}"`);
+    }
+    const author = normalizeAuthor(config.commitAuthor);
+    if (/[\r\n]/.test(config.csp))
+        throw new Error('gh-pages-artifacts: csp must be a single line');
+    return {
+        owner: config.owner === undefined || config.owner === '' ? undefined : config.owner,
+        repo: config.repo,
+        repository: config.repository === undefined || config.repository.trim() === '' ? undefined : parseRepository(config.repository, apiBaseUrl),
+        repoStrategy: config.repoStrategy,
+        repoPrefix: config.repoPrefix,
+        repoVisibility: config.repoVisibility,
+        registryDir: normalizeRegistryDir(config.registryDir),
+        branch: config.branch,
+        siteDir: config.siteDir,
+        pathPrefix,
+        baseUrl,
+        tokenEnv: config.tokenEnv,
+        apiBaseUrl,
+        approval: config.approval,
+        hideFromPresets: [...config.hideFromPresets],
+        subagentAccess: config.subagentAccess,
+        noindex: config.noindex,
+        csp: config.csp.trim(),
+        blockSecrets: config.blockSecrets,
+        maxPublishBytes: config.maxPublishBytes,
+        commitAuthor: author,
+        promptGuidance: config.promptGuidance,
+        bundledSkill: config.bundledSkill,
+    };
+}
+function normalizeAuthor(author) {
+    const name = author?.name?.trim() ?? '';
+    const email = author?.email?.trim() ?? '';
+    if (name === '' && email === '')
+        return undefined;
+    if (name === '' || !/^[^\s@<>]+@[^\s@<>]+$/.test(email)) {
+        throw new Error('gh-pages-artifacts: commitAuthor needs both a non-empty name and a valid email');
+    }
+    return { name, email };
+}
+/**
+ * Parse a repository reference: `owner/name`, `https://<host>/owner/name(.git)`,
+ * `git@<host>:owner/name(.git)`, or `ssh://git@<host>/owner/name(.git)`. The host must be
+ * github.com, or the GitHub Enterprise host behind `apiBaseUrl`.
+ * @param input - user text.
+ * @param apiBaseUrl - normalized API base URL.
+ * @returns owner and repository name.
+ * @throws Error explaining the accepted forms.
+ */
+export function parseRepository(input, apiBaseUrl) {
+    const text = input.trim();
+    const fail = (why) => {
+        throw new Error(`gh-pages-artifacts: "${input}" is not a repository (${why}); use owner/name or a remote URL like https://github.com/owner/name.git`);
+    };
+    let host;
+    let path;
+    const scp = /^[\w.-]+@([^:/\s]+):(.+)$/.exec(text);
+    if (scp !== null) {
+        host = scp[1].toLowerCase();
+        path = scp[2];
+    }
+    else if (/^[a-z][a-z0-9+.-]*:\/\//i.test(text)) {
+        let url;
+        try {
+            url = new URL(text);
+        }
+        catch {
+            return fail('invalid URL');
+        }
+        host = url.hostname.toLowerCase();
+        path = url.pathname;
+    }
+    else if (/^[\w.-]+\.[a-z]{2,}\//i.test(text)) {
+        const slash = text.indexOf('/');
+        host = text.slice(0, slash).toLowerCase();
+        path = text.slice(slash);
+    }
+    else {
+        path = text;
+    }
+    if (host !== undefined) {
+        const apiHost = new URL(apiBaseUrl).hostname.toLowerCase();
+        const allowed = apiHost === 'api.github.com' ? ['github.com', 'www.github.com'] : [apiHost, apiHost.replace(/^api\./, '')];
+        if (!allowed.includes(host))
+            fail(`host ${host} does not match the configured GitHub (${allowed[0]})`);
+    }
+    const segments = path.replace(/^\/+|\/+$/g, '').replace(/\.git$/i, '').split('/');
+    if (segments.length !== 2)
+        fail('expected exactly owner/name');
+    const [owner, repo] = segments;
+    if (!OWNER_PATTERN.test(owner))
+        fail(`invalid owner "${owner}"`);
+    if (!REPO_PATTERN.test(repo) || repo === '.' || repo === '..')
+        fail(`invalid repository name "${repo}"`);
+    return { owner, repo };
+}
+function normalizeRegistryDir(value) {
+    if (value === undefined || value.trim() === '') {
+        const home = process.env['DSH_HOME'] !== undefined && process.env['DSH_HOME'] !== '' ? process.env['DSH_HOME'] : join(homedir(), '.dsh');
+        return join(home, 'gh-pages-artifacts');
+    }
+    if (!isAbsolute(value))
+        throw new Error('gh-pages-artifacts: registryDir must be an absolute path');
+    return value;
+}
+/**
+ * Normalize a relative directory option such as `a` or `pages/a` to slash-joined safe segments.
+ * @param value - raw option value.
+ * @param option - option name for error messages.
+ * @returns the normalized path, '' for the root.
+ */
+export function normalizeRelativeDir(value, option) {
+    const trimmed = value.trim().replace(/^\/+|\/+$/g, '');
+    if (trimmed === '')
+        return '';
+    const segments = trimmed.split('/');
+    for (const segment of segments) {
+        if (!SEGMENT_PATTERN.test(segment)) {
+            throw new Error(`gh-pages-artifacts: ${option} segment "${segment}" must start with a letter or digit and contain only letters, digits, '.', '_' or '-'`);
+        }
+    }
+    return segments.join('/');
+}
+/**
+ * Validate an http(s) URL option and strip its trailing slash.
+ * @param value - raw option value.
+ * @param option - option name for error messages.
+ * @param carriesToken - whether the token is sent to this URL, which then must be HTTPS unless loopback.
+ * @returns the URL without a trailing slash.
+ */
+export function normalizeUrl(value, option, carriesToken) {
+    let url;
+    try {
+        url = new URL(value.trim());
+    }
+    catch {
+        throw new Error(`gh-pages-artifacts: ${option} is not a valid URL: "${value}"`);
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new Error(`gh-pages-artifacts: ${option} must be an http(s) URL`);
+    }
+    if (url.username !== '' || url.password !== '' || url.search !== '' || url.hash !== '') {
+        throw new Error(`gh-pages-artifacts: ${option} must not contain credentials, a query, or a fragment`);
+    }
+    if (carriesToken && url.protocol === 'http:' && !isLoopback(url.hostname)) {
+        throw new Error(`gh-pages-artifacts: ${option} must use https (plain http is allowed only for loopback test servers)`);
+    }
+    return url.href.replace(/\/+$/, '');
+}
+function isLoopback(hostname) {
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
+}

package/lib/content.d.ts

@@ -0,0 +1,43 @@
+/** Read publish sources from the Session workspace and screen text before it goes public. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ToolRunContext } from '@deepseek-ai/dsh-tools';
+/**
+ * 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 declare function readWorkspaceFile(ctx: Context, exec: ToolRunContext, path: string, maxBytes: number): Promise<Uint8Array>;
+/**
+ * The last path segment, used as the default asset name.
+ * @param path - workspace path.
+ */
+export declare function baseName(path: string): string;
+/**
+ * @param name - file name.
+ * @returns whether the name has a text extension.
+ */
+export declare function isTextName(name: string): boolean;
+/**
+ * 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 declare function findSecrets(text: string, knownSecrets?: readonly string[]): string[];
+/**
+ * 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 declare function credentialPathProblem(path: string): string | undefined;
+/**
+ * @param bytes - byte count.
+ * @returns a short human size.
+ */
+export declare function formatBytes(bytes: number): string;