dsh-gh-pages-artifacts 0.1.0

package/lib/service.d.ts

@@ -0,0 +1,292 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { ToolRunContext } from '@deepseek-ai/dsh-tools';
+import { type RepoStrategy, type Settings } from './config.js';
+import { type ArtifactKind } from './manifest.js';
+import { Registry } from './registry.js';
+/** Package version, sent in the User-Agent. */
+export declare const VERSION: string;
+/** Arguments of `artifact_publish`. */
+export interface PublishArgs {
+    readonly description: string;
+    readonly title?: string | undefined;
+    readonly id?: string | undefined;
+    readonly path?: string | undefined;
+    readonly kind?: ArtifactKind | undefined;
+    readonly slug?: string | undefined;
+    readonly assets?: ReadonlyArray<{
+        readonly path: string;
+        readonly name?: string | undefined;
+    }> | undefined;
+    readonly removeAssets?: readonly string[] | undefined;
+    readonly baseRev?: number | undefined;
+    readonly content?: string | undefined;
+}
+/** Result of `artifact_publish`. */
+export interface PublishResult {
+    id: string;
+    title: string;
+    kind: ArtifactKind;
+    url: string;
+    repository: string;
+    newRepository: boolean;
+    rev: number;
+    created: boolean;
+    commit: string;
+    files: string[];
+    warnings: string[];
+}
+/** One row of `artifact_list`. */
+export interface ListedArtifact {
+    id: string;
+    title: string;
+    kind: ArtifactKind;
+    url: string;
+    repository: string;
+    rev: number;
+    updatedAt: string;
+    status: 'published' | 'deleted';
+    description?: string;
+}
+/** Result of `artifact_list`. */
+export interface ListResult {
+    total: number;
+    artifacts: ListedArtifact[];
+    indexFile: string;
+    notes: string[];
+    nextOffset?: number;
+}
+/** Result of `artifact_read`. */
+export interface ReadResult {
+    id: string;
+    title: string;
+    kind: ArtifactKind;
+    url: string;
+    repository: string;
+    rev: number;
+    file: string;
+    files: string[];
+    totalChars: number;
+    offset: number;
+    content: string;
+    nextOffset?: number;
+}
+/** Result of `artifact_delete`. */
+export interface DeleteResult {
+    id: string;
+    url: string;
+    repository: string;
+    deleted: boolean;
+    commit: string;
+    notes: string[];
+}
+/** Result of `artifact_status`. */
+export interface StatusResult {
+    ready: boolean;
+    strategy: RepoStrategy;
+    repository: string;
+    branch: string;
+    siteUrl?: string;
+    token: {
+        configured: boolean;
+        source?: string;
+    };
+    pages: string;
+    /** Head commit of the Pages branch. */
+    headCommit?: string;
+    latestBuild?: {
+        status: string;
+        commit?: string;
+        error?: string;
+    };
+    /** Whether the head commit has been built and deployed; absent when builds are not visible to the token. */
+    deployed?: boolean;
+    artifact?: {
+        id: string;
+        url: string;
+        live: boolean;
+        httpStatus?: number;
+    };
+    registryFile: string;
+    problems: string[];
+}
+/** Arguments of `artifact_repository`. */
+export interface RepositoryArgs {
+    readonly action: 'show' | 'link' | 'unlink' | 'set_strategy';
+    readonly repository?: string | undefined;
+    readonly strategy?: RepoStrategy | undefined;
+}
+/** Result of `artifact_repository`. */
+export interface RepositoryResult {
+    strategy: RepoStrategy;
+    strategySource: 'config' | 'user';
+    repository: string;
+    repositorySource: 'linked' | 'config' | 'token user';
+    branch: string;
+    newRepositories: string;
+    siteUrl?: string;
+    pages?: string;
+    registryFile: string;
+    indexFile: string;
+    warnings: string[];
+}
+/** Hooks replaceable in tests. */
+export interface RuntimeHooks {
+    readonly fetch?: typeof fetch;
+    readonly now?: () => Date;
+    readonly randomSuffix?: () => string;
+    readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/** Topic set on repositories created per artifact, so they are easy to find on GitHub. */
+export declare const ARTIFACT_TOPIC = "dsh-artifact";
+/** Owns configuration-derived state shared by the tools. */
+export declare class ArtifactsRuntime {
+    private readonly ctx;
+    private readonly hooks;
+    /** Local record of everything published, and the user's runtime choices. */
+    readonly registry: Registry;
+    private writeQueue;
+    private readonly logins;
+    private readonly sites;
+    private readonly readSettings;
+    /** Loader entry id of this plugin row, which names its settings namespace. */
+    private readonly namespace;
+    /**
+     * @param ctx - plugin context.
+     * @param settings - settings, or a reader that returns the current ones; options edited on the
+     *   plugin's settings page change while the plugin runs, so they are read per operation.
+     * @param hooks - test hooks.
+     */
+    constructor(ctx: Context, settings: Settings | (() => Settings), hooks?: RuntimeHooks, namespace?: string);
+    /** The current settings. */
+    get settings(): Settings;
+    private now;
+    private randomSuffix;
+    /**
+     * Resolve the GitHub token for one operation; never cached.
+     * @returns the token value, or undefined when not configured.
+     */
+    resolveToken(): Promise<{
+        value: string;
+        source: string;
+    } | undefined>;
+    private missingTokenError;
+    private api;
+    private login;
+    /** The token's own account, refused when the token could come from an untrusted project .env. */
+    private tokenOwner;
+    /** @returns the effective strategy and whether the user changed it at runtime. */
+    private strategyOf;
+    /** The shared repository: a linked one, then the configured one, then `repo` under the token's user. */
+    private sharedRepository;
+    private sharedLocation;
+    private ownLocation;
+    private store;
+    /**
+     * Find where an existing artifact lives: the registry first, then the shared repository's
+     * manifest (for artifacts published from another machine).
+     */
+    private locate;
+    /**
+     * Discover the public site URL and Pages state of one repository, cached for a few minutes.
+     */
+    private siteInfo;
+    private artifactUrl;
+    /**
+     * Turn GitHub Pages on for a repository when it is off. Pushing a gh-pages branch usually does
+     * this by itself, so a brand-new repository first gets a few seconds to catch up; otherwise the
+     * token needs Pages and Administration write. Never throws: the page is already committed, so a
+     * problem here only becomes a warning for the user.
+     * @returns warnings for the user when Pages could not be enabled.
+     */
+    private ensurePages;
+    /** Create the repository of a new per-artifact location. */
+    private createRepository;
+    /**
+     * Enforce the visibility policy at execution time too, so a missed or failed per-Agent
+     * restriction can never open a mutating tool to a subagent or a hidden preset.
+     */
+    private assertVisible;
+    private serialized;
+    /** Record a published or updated artifact in the registry. */
+    private track;
+    /**
+     * Create a new artifact or update one in place.
+     * @param args - tool arguments.
+     * @param exec - tool execution.
+     */
+    publish(args: PublishArgs, exec: ToolRunContext): Promise<PublishResult>;
+    private readSources;
+    /**
+     * List tracked artifacts, newest first. Artifacts found in the shared repository but missing
+     * from the local registry (published from another machine) are added to it.
+     * @param args - filter and paging.
+     * @param signal - cancellation.
+     */
+    list(args: {
+        query?: string | undefined;
+        offset?: number | undefined;
+        limit?: number | undefined;
+        includeDeleted?: boolean | undefined;
+    }, signal: AbortSignal): Promise<ListResult>;
+    /**
+     * Find repositories created per artifact (tagged with the artifact topic) that the registry does
+     * not know yet, for example ones published from another machine, and track their artifacts.
+     */
+    private discoverOwnRepositories;
+    /**
+     * Read an artifact's source or one of its text files.
+     * @param args - id, file, window.
+     * @param signal - cancellation.
+     */
+    read(args: {
+        id: string;
+        file?: string | undefined;
+        offset?: number | undefined;
+        limit?: number | undefined;
+    }, signal: AbortSignal): Promise<ReadResult>;
+    /**
+     * Delete an artifact for the agent; its id is never reused. Asks for approval per configuration.
+     * @param args - id.
+     * @param exec - tool execution.
+     */
+    remove(args: {
+        id: string;
+    }, exec: ToolRunContext): Promise<DeleteResult>;
+    /**
+     * Delete an artifact the user chose in the Artifacts panel. The click (after the panel's own
+     * confirmation) is the user's decision, so the agent approval prompt does not apply.
+     * @param id - artifact id.
+     * @param signal - cancellation.
+     */
+    removeByUser(id: string, signal: AbortSignal): Promise<DeleteResult>;
+    private deleteArtifact;
+    /**
+     * Show or change where new artifacts go.
+     * @param args - action and its inputs.
+     * @param exec - tool execution.
+     */
+    repository(args: RepositoryArgs, exec: ToolRunContext): Promise<RepositoryResult>;
+    /**
+     * Persist a choice made in chat. With the dsh settings service the plugin's own configuration is
+     * updated, so the Plugins page and the profile file show it; without it (or when a higher layer
+     * fixes the value) the choice is kept in the registry, which then overrides the configuration.
+     */
+    private saveChoice;
+    private describeRepository;
+    /**
+     * Diagnose the setup and the deployment of the latest change.
+     * @param args - optional artifact id and whether to wait for deployment.
+     * @param signal - cancellation.
+     */
+    status(args: {
+        id?: string | undefined;
+        wait?: boolean | undefined;
+    }, signal: AbortSignal): Promise<StatusResult>;
+    private probe;
+}
+/**
+ * The default public URL of a project site, or of a user/organization site repository.
+ * @param owner - repository owner.
+ * @param repo - repository name.
+ */
+export declare function defaultSiteUrl(owner: string, repo: string): string;