@huanlin/dsh-plugin-aigc-canvas 0.1.0 → 0.1.2

package/lib/invariant.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Package-owned invariant companion for `@dsh-external/dsh-aigc-canvas`.
+ * @module @dsh-external/dsh-aigc-canvas/invariant
+ */
+import type { Context } from './context-types.js';
+/** Cordis companion plugin name. */
+export declare const name = "dsh-aigc-canvas-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;

package/lib/invariant.js

@@ -1,5 +1,5 @@
 //#region src/invariant.ts
-const PACKAGE_NAME = "@huanlin/dsh-plugin-aigc-canvas";
+const PACKAGE_NAME = "@dsh-external/dsh-aigc-canvas";
 /** Cordis companion plugin name. */
 const name = "dsh-aigc-canvas-invariant";
 /** Service required before the companion can reserve package ownership. */
@@ -7,7 +7,7 @@ const inject = ["invariants"];
 /**
 * No runtime invariant: the canvas owns no service state or event protocol
 * of its own beyond the registry's own assertions (uuid existence, kind
-* checks) — every route is mounted under the host's webServer fence, the
+* checks) — every route is mounted under the host's httpServer fence, the
 * element table is exercised by the smoke spec, and the client view is a
 * pure projection of the host state.
 */

package/lib/media-edit.d.ts

@@ -0,0 +1,38 @@
+/** The operations the tool supports. */
+export type MediaEditOperation = 'concat' | 'clip' | 'extract_audio' | 'extract_frame' | 'speed' | 'resize' | 'reverse' | 'add_audio' | 'images_to_video';
+/** All operations as a readonly array (for schema enum + validation). */
+export declare const MEDIA_EDIT_OPERATIONS: readonly MediaEditOperation[];
+/** One operation request (already validated by the tool layer). */
+export interface MediaEditRequest {
+    operation: MediaEditOperation;
+    inputs: string[];
+    outputExt: string;
+    start?: number;
+    end?: number;
+    duration?: number;
+    speed?: number;
+    width?: number;
+    height?: number;
+    fps?: number;
+    timestamp?: number;
+}
+/** Result of a successful media edit. */
+export interface MediaEditResult {
+    outputPath: string;
+    operation: MediaEditOperation;
+    durationMs: number;
+}
+/**
+ * Execute one media edit operation. Builds the ffmpeg argv, runs it, and
+ * writes the output to the canvas directory.
+ *
+ * @param request - the validated operation request.
+ * @param cwd - the session cwd (canvas dir = cwd/.dsh-aigc-canvas/sessionId/).
+ * @param sessionId - the session id (for the canvas dir path).
+ * @param opts - timeout + abort signal.
+ * @returns the output file path and timing info.
+ */
+export declare function executeMediaEdit(request: MediaEditRequest, cwd: string, sessionId: string, opts: {
+    timeoutMs: number;
+    signal?: AbortSignal;
+}): Promise<MediaEditResult>;

package/lib/provider-http.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Generic HTTP executor for one provider: the `aigc_http_request` tool's
+ * engine. Builds the request URL from the provider endpoint + a relative
+ * path, attaches the apiKey per the provider's `auth` config (default
+ * `Authorization: Bearer <key>`), and runs it with a bounded timeout.
+ *
+ * Security boundary:
+ * - Only relative request paths are allowed (`/foo/bar`), never absolute
+ *   URLs — every request stays on the provider's configured endpoint.
+ * - The apiKey never enters the tool output; only the response does.
+ *
+ * Stub mode: when the endpoint is `stub://aigc-backend` (or empty), the
+ * executor returns synthetic media so the whole flow (http → file → place)
+ * can be exercised without a real API. The stub media kind is inferred from
+ * the request path / body (image/video/audio), defaulting to JSON text.
+ */
+import type { ResolvedAigcProvider } from './config.js';
+/** Binary kinds the executor can hand back (for canvas placement). */
+export type ProviderBinaryKind = 'image' | 'video' | 'audio' | 'other';
+/** Text response kinds (inline for the model). */
+export type ProviderTextKind = 'json' | 'text';
+/** One raw request the model wants to send to the provider API. */
+export interface ProviderHttpRequest {
+    /** HTTP method (default GET). */
+    method?: string;
+    /**
+     * Path relative to the provider endpoint, e.g. `/v1/images/generations`.
+     * Must start with `/`.
+     *
+     * Absolute URLs are also accepted, but only when same-origin with the
+     * provider's configured endpoint (same protocol + host + port). This lets
+     * the model fetch provider-returned download URLs (e.g. video result URLs)
+     * that require the provider's auth, without opening an SSRF surface.
+     */
+    path: string;
+    /** Extra request headers (may not override the auth header). */
+    headers?: Record<string, string>;
+    /** Raw request body (string, typically JSON). */
+    body?: string;
+    /** URL query params to append (merged with any auth query param). */
+    query?: Record<string, string>;
+}
+/** A successful binary response (persisted by the caller). */
+export interface ProviderHttpBinary {
+    ok: true;
+    status: number;
+    kind: ProviderBinaryKind;
+    contentType: string;
+    bytes: Buffer;
+    /** Bytes length (the caller's file size). */
+    size: number;
+}
+/** A successful text response (embedded inline for the model). */
+export interface ProviderHttpText {
+    ok: true;
+    status: number;
+    kind: ProviderTextKind;
+    contentType: string;
+    text: string;
+}
+/** A failed response (non-2xx): the body is surfaced so the model can adapt. */
+export interface ProviderHttpFailure {
+    ok: false;
+    status: number;
+    contentType: string;
+    /** Truncated response body (UTF-8) for the model to read. */
+    text: string;
+}
+export type ProviderHttpResult = ProviderHttpBinary | ProviderHttpText | ProviderHttpFailure;
+/**
+ * Cap on inline text responses. The model-facing tool result is size-
+ * limited by the host framework (very small — a few hundred chars), so
+ * anything larger is saved to disk and the model gets a file_path with a
+ * short preview instead.
+ */
+export declare const INLINE_TEXT_CAP = 2000;
+/** Execute one request against the provider (or the built-in stub). */
+export declare function executeProviderRequest(provider: ResolvedAigcProvider, request: ProviderHttpRequest, opts: {
+    timeoutMs: number;
+    signal?: AbortSignal;
+}): Promise<ProviderHttpResult>;

package/lib/provider-store.d.ts

@@ -0,0 +1,50 @@
+import type { AigcProvider, ResolvedAigcProvider } from './config.js';
+/** CRUD result: the success branch carries the latest list. */
+export type ProviderMutationResult = {
+    readonly ok: true;
+    readonly providers: readonly ResolvedAigcProvider[];
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Mutable provider store. Owns the canonical provider list; the backend
+ * client map and RPC handlers share one instance per plugin fiber.
+ *
+ * Persistence: on construction the store loads `~/.dsh/aigc-canvas/
+ * providers.json` (if present) and merges it over the cordis.yml seed —
+ * persisted providers win, so user edits and deletions survive restarts.
+ * Every mutation writes the list back to disk (fire-and-forget).
+ */
+export declare class ProviderStore {
+    private readonly providers;
+    private readonly dataPath;
+    /** Serializes disk writes so rapid mutations can't interleave. */
+    private persistChain;
+    constructor(seed: readonly AigcProvider[], dataPath?: string);
+    /** Snapshot of all providers, in insertion order. */
+    list(): readonly ResolvedAigcProvider[];
+    /** Look up one provider by id. */
+    get(id: string): ResolvedAigcProvider | undefined;
+    /** The default provider (first in insertion order); undefined if empty. */
+    defaultProvider(): ResolvedAigcProvider | undefined;
+    /** Add a new provider. Returns failure for duplicate id or invalid shape. */
+    add(provider: AigcProvider): ProviderMutationResult;
+    /** Update an existing provider. Returns failure if the id is unknown. */
+    update(provider: AigcProvider): ProviderMutationResult;
+    /**
+     * Replace a provider's usage instructions (called by the model's
+     * aigc_provider_set_instructions tool after it probes the API).
+     */
+    setInstructions(id: string, instructions: string): ProviderMutationResult;
+    /** Remove a provider. Returns failure for unknown id. */
+    remove(id: string): ProviderMutationResult;
+    /**
+     * Persist the current provider list to disk (fire-and-forget, serialized).
+     * Only the user-editable fields are written; `builtin` is re-derived from
+     * the seed on load. Failures are swallowed — the in-memory state stays
+     * canonical. Each call snapshots the CURRENT list, so a burst of mutations
+     * ends with the latest state on disk.
+     */
+    private persist;
+}

package/lib/tools.d.ts

@@ -0,0 +1,47 @@
+import type { Context } from './context-types.js';
+import type { ResolvedAigcProvider } from './config.js';
+import type { AigcElement, AigcCanvasService } from './canvas-registry.js';
+/** Truncate a prompt to a short title (first line, capped). */
+declare function titleOf(prompt: string): string;
+/**
+ * The model-facing shape of one element (no internal uuid, no media bytes).
+ * The `filePath` is the primary identifier the agent uses to reference
+ * the element in subsequent tool calls; `x`/`y` are the canvas position.
+ */
+declare function elementProjection(el: AigcElement): Record<string, unknown>;
+/** Edge projection: resolve uuids to filePaths so the agent can read the graph. */
+declare function edgeProjection(edge: {
+    source: string;
+    target: string;
+}, lookup: (uuid: string) => AigcElement): {
+    source: string;
+    target: string;
+};
+/** Info about one provider (for the aigc_get_provider_info tool output). */
+export interface ProviderInfo {
+    id: string;
+    name: string;
+    endpoint: string;
+    instructions: string;
+    isStub: boolean;
+    isDefault: boolean;
+}
+/**
+ * Register the seven tools against the host tool registry.
+ *
+ * @param ctx - host plugin context (carries the tools service).
+ * @param getProvider - live provider getter (takes optional provider id).
+ * @param setInstructions - persists usage instructions for one provider (the host's ProviderStore).
+ * @param listProviders - returns info for all providers (for aigc_get_provider_info).
+ * @param canvas - the canvas registry service (host-owned state).
+ * @param resolveCwd - live cwd resolver for one session id.
+ * @param getTimeoutMs - live per-request timeout for aigc_http_request.
+ * @param getMediaLimit - live cap on bytes the http tool may write to disk.
+ * @returns a disposer that unregisters all tools.
+ */
+export declare function registerTools(ctx: Context, getProvider: (providerId?: string) => ResolvedAigcProvider, setInstructions: (id: string, instructions: string) => {
+    ok: boolean;
+    error?: string;
+}, listProviders: () => readonly ProviderInfo[], canvas: AigcCanvasService, resolveCwd: (sessionId: string) => string, getTimeoutMs: () => number, getMediaLimit?: () => number): () => void;
+/** Re-export the projection helpers for the unit tests. */
+export { elementProjection, edgeProjection, titleOf };

package/lib/trust-fence.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Browser-trust fence for the aigc-canvas routes, behaviorally identical to
+ * the /api gateway's fence in @deepseek-ai/dsh-client-connection
+ * (src/api-request-trust.ts + src/loopback-hostname.ts, BSD-3-Clause,
+ * copied verbatim from dsh-better-sidebar's src/trust-fence.ts because the
+ * package does not export these helpers and the plugin must not depend on
+ * its internals). Host-header loopback or a configured trusted authority
+ * passes; cross-site browser markers refuse. This is a DNS-rebinding /
+ * cross-site defense, not authentication.
+ */
+import type { IncomingHttpHeaders } from 'node:http';
+/** The request facts the fence reads (structural subset of IncomingMessage). */
+interface ApiTrustRequest {
+    headers: IncomingHttpHeaders;
+}
+/** Whether a normalized URL hostname names the local loopback authority. */
+export declare function isLoopbackHostname(hostname: string): boolean;
+/**
+ * Decide whether one aigc-canvas request may reach the plugin routes.
+ * @param request - node HTTP request facts (headers).
+ * @param trustedHosts - non-loopback authorities this deployment serves.
+ * @returns true when the Host is ours (loopback or trusted) and browser markers are same-origin.
+ */
+export declare function isTrustedApiRequest(request: ApiTrustRequest, trustedHosts: readonly string[]): boolean;
+export {};

package/lib/wire.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Wire helpers for the /aigc-canvas JSON API: bounded body reading, response
+ * writing, and the shared error envelope. Every API method returns
+ * `{ ok: true, value }` on success and `{ ok: false, error: { code, message } }`
+ * (HTTP 4xx/5xx matching the code) on failure — mirrors better-sidebar's
+ * `/sidebar/api/*` envelope so the client-side fetch helper is identical.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** Machine-readable error codes of the canvas API. */
+export type AigcErrorCode = 'bad-request' | 'not-found' | 'forbidden' | 'method-error' | 'fs-error' | 'backend-error' | 'internal';
+/** One API failure with its wire code and HTTP status. */
+export declare class AigcError extends Error {
+    readonly code: AigcErrorCode;
+    readonly status: number;
+    constructor(code: AigcErrorCode, message: string, status?: number);
+}
+/** Success envelope of one API method. */
+export interface AigcOk<T> {
+    ok: true;
+    value: T;
+}
+/** Failure envelope of one API method. */
+export interface AigcErr {
+    ok: false;
+    error: {
+        code: AigcErrorCode;
+        message: string;
+    };
+}
+/** Read and parse the JSON request body (bounded; malformed → bad-request). */
+export declare function readJsonBody(req: IncomingMessage): Promise<unknown>;
+/** Write a JSON response with the given status. */
+export declare function writeJson(res: ServerResponse, status: number, body: unknown): void;
+/** Write the success envelope. */
+export declare function writeOk(res: ServerResponse, value: unknown): void;
+/** Write the failure envelope for any thrown value (unknown → internal 500). */
+export declare function writeError(res: ServerResponse, error: unknown): void;
+/** Narrow an unknown payload value to a string, else throw bad-request. */
+export declare function requireString(payload: unknown, key: string): string;
+/** Narrow an unknown payload value to an array of strings (default [] when absent). */
+export declare function optionalStringArray(payload: unknown, key: string): string[];

package/package.json

@@ -1,13 +1,9 @@
 {
   "name": "@huanlin/dsh-plugin-aigc-canvas",
-  "version": "0.1.0",
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": ["dsh-plugin"],
-  "description": "DSH plugin: provider-agnostic AIGC HTTP bridge + free canvas + ffmpeg post-processing. Exposes aigc_get_provider_info / aigc_http_request (endpoint + apiKey auto-attached) / aigc_provider_set_instructions / aigc_provider_get_instructions / aigc_canvas_place / aigc_canvas_link / aigc_canvas_unlink / aigc_canvas_list_elements / aigc_media_edit tools; generated files are placed at arbitrary canvas positions and can be double-clicked for prompt + params.",
+  "version": "0.1.2",
+  "description": "DSH plugin: an infinite free canvas for the better-sidebar plus provider-agnostic generation. Exposes aigc_get_provider_info / aigc_http_request (endpoint + apiKey auto-attached) / aigc_provider_set_instructions / aigc_canvas_place / aigc_canvas_link / aigc_canvas_unlink / aigc_canvas_list_elements tools; generated files are placed at arbitrary canvas positions and can be double-clicked for prompt + params.",
   "type": "module",
-  "license": "AGPL-3.0",
+  "license": "MIT",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
   "exports": {
@@ -59,24 +55,23 @@
     "test:watch": "vitest",
     "build": "tsdown --config tsdown.config.ts && tsc -p tsconfig.build.json",
     "bundle:client": "tsdown --config tsdown.config.ts",
-    "watch": "tsdown --config tsdown.config.ts --watch",
-    "prepare": "tsdown --config tsdown.prepare.config.ts"
+    "watch": "tsdown --config tsdown.config.ts --watch"
   },
   "dependencies": {
     "schemastery": "^3.18.0",
     "ws": "^8.18.0"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-client-locale": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-client-runtime": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.0.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
     "cordis": "^4.0.0-rc.7",
     "dsh-better-sidebar": "^0.4.0",
     "react": "^18.2.0",
@@ -99,16 +94,16 @@
     "react-dom": { "optional": true }
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-client-locale": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-client-runtime": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-locale": "link:C:/Users/Administrator/.dsh/source/current/packages/client/locale",
+    "@deepseek-ai/dsh-client-runtime": "link:C:/Users/Administrator/.dsh/source/current/packages/client/runtime",
+    "@deepseek-ai/dsh-client-ui-primitives": "link:C:/Users/Administrator/.dsh/source/current/packages/client/ui-primitives",
+    "@deepseek-ai/dsh-client-ui-settings": "link:C:/Users/Administrator/.dsh/source/current/packages/client/ui-settings",
+    "@deepseek-ai/dsh-client-ui-conversation": "link:C:/Users/Administrator/.dsh/source/current/packages/client/ui-conversation",
+    "@deepseek-ai/dsh-client-ui-slots": "link:C:/Users/Administrator/.dsh/source/current/packages/client/ui-slots",
+    "@deepseek-ai/dsh-host-webserver": "link:C:/Users/Administrator/.dsh/source/current/packages/host/webserver",
+    "@deepseek-ai/dsh-invariants": "link:C:/Users/Administrator/.dsh/source/current/packages/support/invariants",
+    "@deepseek-ai/dsh-session": "link:C:/Users/Administrator/.dsh/source/current/packages/core/session",
+    "@deepseek-ai/dsh-tools": "link:C:/Users/Administrator/.dsh/source/current/packages/core/tools",
     "@types/node": "^24.0.0",
     "@types/react": "~18.3.1",
     "@types/react-dom": "~18.3.1",