@javierfrancoleal/plugin-authoring 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 J.Franco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# @javierfrancoleal/plugin-authoring
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Skill de **autoría de plugins** para DeepSeek Harness. Registra la skill
+`plugin-authoring`, cuyo cuerpo (`assets/plugin-authoring.md`) contiene la guía
+destilada para crear y publicar plugins sin redescubrir la arquitectura.
+
+La skill cubre: los tres tipos de plugin (host / cliente / doble cara), la anatomía
+de `package.json` + `cordis.patch.yml`, el half host (skills/comandos/efectos), el
+half browser (`dsh.client` + `window.__ModuleLoader__` + slots), locale, tokens de
+tema, instalación, gotchas y checklist de validación.
+
+## Uso
+
+- **Agentes**: cargar la skill `plugin-authoring` antes de crear o extender un plugin.
+- **Humanos**: leer `docs/PLUGIN-AUTHORING.md` (fuente canónica), copiar la plantilla
+  `templates/dsh-plugin/`, y usar `tools/new-plugin.sh` + `tools/check-plugin.sh`.
+
+## Instalación
+
+Como cualquier bundle: añadir `@javierfrancoleal/plugin-authoring` a
+`dsh.profile.bundles` (y su dependencia `link:`), `pnpm install`, y reiniciar la app.
+
+Creado por **J.Franco**.

package/assets/plugin-authoring.md

@@ -0,0 +1,186 @@
+# How to author a DeepSeek Harness plugin (distilled)
+
+DSH is a **Cordis** runtime. A plugin is an npm package with one or two halves:
+
+- **Host half** `lib/index.js` (Node): skills, commands, services, scheduled work.
+- **Browser half** `lib/client.js` (React): UI in the Web GUI.
+
+Activation is via `cordis.patch.yml`, which inserts the plugin's row into the Loader.
+
+## Three kinds
+
+| Kind | `dsh.bundle.patch` | `dsh.client` |
+|---|---|---|
+| Host-only (skill / command) | yes | no |
+| Client-only (UI) | no | yes |
+| Dual-face | yes | yes |
+
+## Files
+
+```
+mi-plugin/
+├── package.json        # exports + dsh.bundle.patch + dsh.client
+├── cordis.patch.yml    # - insert: - id: mi-plugin  name: '@scope/mi-plugin'
+├── lib/index.js        # host half — export apply(ctx)
+├── lib/client.js       # browser half — window.__ModuleLoader__.load(...)
+├── locale/*.json       # meta.title / meta.description
+├── icon.svg
+└── README.md
+```
+
+## package.json (dual-face minimum)
+
+```jsonc
+{
+  "name": "@javierfrancoleal/mi-plugin",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "engines": { "node": ">=24", "dsh": ">=0.2.1-rc.0" },
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": { "patch": "./cordis.patch.yml" },
+    "client": {
+      "platform": "web",
+      "inject": ["@deepseek-ai/dsh-client-locale", "@deepseek-ai/dsh-client-ui-layout"]
+    }
+  },
+  "peerDependencies": { "@deepseek-ai/cordis": "~4.0.5" }
+}
+```
+
+## Host half — register a skill (proven pattern)
+
+```js
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { BUNDLED_SKILL_RANK } from "@deepseek-ai/dsh-skill";
+
+const PROVIDER_NAME = "javierfrancoleal-mi-plugin";
+const SKILL_BODY_URL = new URL("../assets/mi-skill.md", import.meta.url);
+const RESOURCE_BASE = { kind: "directory", path: fileURLToPath(new URL("../assets/", import.meta.url)) };
+const CANDIDATE = {
+  name: "mi-skill",
+  description: "…",
+  invocation: { modelInvocable: true, userInvocable: true },
+  provider: PROVIDER_NAME, source: "bundled",
+  resourceBase: RESOURCE_BASE, rank: BUNDLED_SKILL_RANK, locator: SKILL_BODY_URL,
+};
+const provider = {
+  name: PROVIDER_NAME,
+  list: () => Promise.resolve([CANDIDATE]),
+  async get() { return { ...CANDIDATE, content: await readFile(SKILL_BODY_URL, "utf8") }; },
+};
+const name = "mi-plugin";
+const inject = ["skills"];
+function apply(ctx) { ctx.skills.registerProvider(() => provider); }
+export { apply, inject, name };
+```
+
+Commands: `ctx.get("commands")?.register({ definitionId, name, description, input, handler })`.
+Timers: `ctx.effect(() => { const t = setTimeout(run, ms); return () => clearTimeout(t); }, "label")`.
+Log: `ctx.logger.info/warn(...)`.
+
+## Browser half — the recipe (the hard part)
+
+```js
+window.__ModuleLoader__.load({
+  id: "@javierfrancoleal/mi-plugin",
+  factory: (require) => {
+    var module = { exports: {} };
+    var exports = module.exports;
+    Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+    const React = require("react");   // react + react/jsx-runtime are baseline
+
+    function MiComponente(_props) {
+      const t = _props && typeof _props.t === "function" ? _props.t : (k) => k;
+      return React.createElement("div", null, t("saludo"));
+    }
+
+    const inject = ["slots", "locale"];
+    function apply(ctx) {
+      ctx.effect(() => ctx.locale.register("miNs", { zh, en }), "mi-plugin: locale");
+      ctx.slots.inject("shell.bottom", () => ctx.slots.register({
+        name: "shell.bottom", id: "mi-plugin", order: 0, locale: "miNs"
+      }, MiComponente));
+    }
+
+    exports.MiComponente = MiComponente;
+    exports.apply = apply;
+    exports.inject = inject;
+    return module.exports;
+  }
+});
+```
+
+Rules:
+- `exports["./client"]` → `./lib/client.js`.
+- Write `lib/client.js` **already built** (this exact form); no build step for `link:` installs.
+- No JSX — use `React.createElement` or `require("react/jsx-runtime")`.
+- Inject CSS with a `<style data-plugin-css="…">` tag.
+- Client `inject` lists **services** (`slots`, `locale`, `theme`, `remote`, …).
+
+## Slots
+
+| Slot | Alcance | Para qué |
+|---|---|---|
+| `shell.bottom` | root | **global full-width bottom bar** (empty by default) |
+| `shell.overlay` / `shell.leading` | root | overlay / top-left corner |
+| `sidebar` / `rightbar` / `main` | root | columns / central panel |
+| `conversation.input.dock` | sesión | bar above the composer |
+
+`ctx.slots.inject(slot, () => ctx.slots.register(opts, Component))` is deferred.
+
+## Locale & theme
+
+- `ctx.locale.register(ns, { zh, en })` — **both** dictionaries required.
+- `locale: ns` in `register` → framework injects `t` as a prop.
+- Theme tokens (light/dark aware, no hardcoded hex): `--dsw-alias-label-primary/secondary/tertiary`,
+  `--dsw-alias-state-success-primary` (green), `-warn-primary` (amber), `-error-primary` (red),
+  `--dsw-specific-menu`, `--dsw-alias-border-l1`, `--dsw-radius-md`, `--dsw-elevation-panel`,
+  `--dsw-menu-backdrop-filter`.
+
+## Install into the running app
+
+**A) From npm** (another machine/profile without the local checkout):
+
+```bash
+dsh plugin --profile <perfil> add @javierfrancoleal/mi-plugin
+```
+
+This adds the dependency + bundle and runs pnpm for you; restart the app after.
+
+**B) Local (`link:`) — developing in the monorepo:**
+
+1. `~/.dsh/profiles/<perfil>/package.json`: add `"@scope/nombre": "link:/abs/path"` to
+   `dependencies` and `"@scope/nombre"` to `dsh.profile.bundles`.
+2. `cd ~/.dsh/profiles/<perfil> && pnpm install`.
+3. **Restart the app** (a new bundle needs a host recomposition).
+
+## Gotchas
+
+1. The checkout lives inside `app.asar` — use `_dsh-inspect/asar-tool.mjs list|extract`.
+2. The `desktop` profile is Electron-managed: `dsh --profile desktop --dump-config` fails.
+   Validate with a throwaway profile.
+3. New bundles are NOT picked up by HMR on external edits — restart the app.
+4. `dsh.bundle.patch` + `dsh.client` can coexist (dual-face).
+5. React / slots / primitives are baseline; don't list them in `dsh.client.inject`.
+
+## Validation checklist
+
+```bash
+node --check lib/index.js && node --check lib/client.js
+node tools/check-client.mjs lib/client.js
+dsh --profile testprices --dump-config | grep mi-plugin     # throwaway profile, not desktop
+curl -sS http://127.0.0.1:<puerto>/plugins/@scope/mi-plugin/client.js   # 200 after restart
+```
+
+Full reference: `docs/PLUGIN-AUTHORING.md`. Template: `templates/dsh-plugin/`.
+Scaffold/validate: `tools/new-plugin.sh`, `tools/check-plugin.sh`.

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# @javierfrancoleal/plugin-authoring — authoring skill for new DSH plugins.
+- insert:
+    - id: plugin-authoring
+      name: '@javierfrancoleal/plugin-authoring'

package/icon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128" fill="none">
+  <rect width="128" height="128" rx="24" fill="#7C5CFF"/>
+  <path d="M38 34 H90 V54 H38 Z" fill="#ffffff" opacity="0.35"/>
+  <path d="M38 62 H90 V82 H38 Z" fill="#ffffff" opacity="0.7"/>
+  <path d="M38 90 H90 V100 H38 Z" fill="#ffffff"/>
+  <circle cx="98" cy="44" r="7" fill="#ffffff"/>
+  <path d="M92 44 H104 M98 38 V50" stroke="#ffffff" stroke-width="3" stroke-linecap="round"/>
+</svg>

package/lib/index.js

@@ -0,0 +1,53 @@
+// @javierfrancoleal/plugin-authoring — host half.
+// Registers the `plugin-authoring` skill so agents can load the distilled
+// guide for building DeepSeek Harness plugins without re-discovering the
+// architecture. The skill body lives in assets/plugin-authoring.md.
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { BUNDLED_SKILL_RANK } from "@deepseek-ai/dsh-skill";
+
+const PROVIDER_NAME = "javierfrancoleal-plugin-authoring";
+const SKILL_BODY_URL = new URL("../assets/plugin-authoring.md", import.meta.url);
+const RESOURCE_BASE = {
+  kind: "directory",
+  path: fileURLToPath(new URL("../assets/", import.meta.url)),
+};
+
+const CANDIDATE = {
+  name: "plugin-authoring",
+  description: "Build and publish a DeepSeek Harness plugin (host-only, client-only, or dual-face) without re-discovering the architecture: package.json anatomy, cordis.patch.yml, the browser-half recipe (dsh.client + window.__ModuleLoader__ + slots), locale, theme tokens, install steps, gotchas, and the validation checklist. Load before creating or extending any DSH plugin.",
+  invocation: {
+    modelInvocable: true,
+    userInvocable: true,
+  },
+  provider: PROVIDER_NAME,
+  source: "bundled",
+  resourceBase: RESOURCE_BASE,
+  rank: BUNDLED_SKILL_RANK,
+  locator: SKILL_BODY_URL,
+};
+
+const provider = {
+  name: PROVIDER_NAME,
+  list: () => Promise.resolve([CANDIDATE]),
+  async get(_candidate) {
+    return {
+      name: CANDIDATE.name,
+      description: CANDIDATE.description,
+      invocation: CANDIDATE.invocation,
+      provider: CANDIDATE.provider,
+      source: CANDIDATE.source,
+      resourceBase: RESOURCE_BASE,
+      content: await readFile(SKILL_BODY_URL, "utf8"),
+    };
+  },
+};
+
+const name = "plugin-authoring";
+const inject = ["skills"];
+
+function apply(ctx) {
+  ctx.skills.registerProvider(() => provider);
+}
+
+export { apply, inject, name };

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Plugin Authoring",
+    "description": "Skill that teaches how to build and publish DeepSeek Harness plugins (host, client, or dual-face) without re-discovering the architecture."
+  }
+}

package/locale/es.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Autoría de plugins",
+    "description": "Skill que enseña a crear y publicar plugins de DeepSeek Harness (host, cliente o doble cara) sin redescubrir la arquitectura."
+  }
+}

package/locale/fr.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Création de plugins",
+    "description": "Compétence qui enseigne à créer et publier des plugins DeepSeek Harness (hôte, client ou double-face) sans redécouvrir l'architecture."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "插件编写",
+    "description": "教授如何构建和发布 DeepSeek Harness 插件（宿主、客户端或双面），无需重新发现架构。"
+  }
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@javierfrancoleal/plugin-authoring",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.1",
+  "description": "Plugin-authoring skill for DeepSeek Harness: the distilled anatomy, client-UI recipe, slots, locale, theme tokens, install steps, gotchas, and validation checklist for building and publishing new DSH plugins.",
+  "author": "J.Franco",
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "icon": "./icon.svg",
+  "files": [
+    "icon.svg",
+    "locale/*.json",
+    "lib/index.js",
+    "assets",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24",
+    "dsh": ">=0.2.1-rc.0"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "plugin-authoring",
+    "scaffold",
+    "skill"
+  ],
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5",
+    "@deepseek-ai/dsh-skill": ">=0.2.1-rc.5"
+  }
 }