@danxbot/plugin-sdk 0.1.2 → 0.1.4

package/README.md

@@ -1,54 +1,60 @@
-# @danxbot/plugin-sdk
-
-Build a 50 Arms **card-type plugin**: a small React bundle that gives a card type its own card view (`CardView`) and/or card-list view (`CardListView`), loaded into 50 Arms' own page with `import()`.
-
-A plugin does not bundle React, `@danxbot/ui` or the card features. The app serves them under fixed import specifiers through an import map, so a plugin shares the app's single React and renders the app's own components:
-
-| Specifier | What it is |
-|---|---|
-| `react`, `react/jsx-runtime`, `react-dom` | The app's React |
-| `@danxbot/ui` | The app's design system |
-| `@danxbot/card-kit@1` | The card features: data hooks, card regions (`StandardCardPage`, `EditableTitle`, `ChecklistsSection`, ...), `CardFace`, `CardBoard` |
-
-The live list and each library's major version is `GET /api/plugin-runtime`.
-
-## Set up a plugin
-
-`package.json`: depend on `@danxbot/plugin-sdk` and install its peers: `vite`, `react`, `@types/react`, `@danxbot/ui` and `react-router` (types only: the app serves the real ones; the kit's declarations import them).
-
-`vite.config.ts`:
-
-```ts
-import { defineConfig } from "vite";
-import { danxPlugin } from "@danxbot/plugin-sdk/vite";
-
-export default defineConfig({ plugins: [danxPlugin()] });
-```
-
-`tsconfig.json`: add `"types": ["@danxbot/plugin-sdk/card-kit"]`: the kit's declarations. They are self-contained (they import only `react`, `@danxbot/ui` and `react-router`) and the specifier is not a package, so TypeScript reads them as ambient types.
-
-`src/index.tsx` exports `CardView` and/or `CardListView`:
-
-```tsx
-import { StandardCardPage, type CardViewProps } from "@danxbot/card-kit@1";
-
-export function CardView({ card, mutation }: CardViewProps) {
-  return <StandardCardPage card={card} mutation={mutation} />;
-}
-```
-
-`vite build` writes the plugin to `dist/`: `index.js` (the entry), `chunks/` for code splitting, `index.css`, source maps, and `danx-plugin.json`, the manifest listing every file with its size and sha256 and the runtime majors the plugin was built against.
-
-The build refuses to bundle a copy of React, React DOM, `@danxbot/ui` or `react-router`: import only the specifiers above. For routing, use the kit's `Link` and `useNavigate`; `StandardCardPage` reads the plan the page was opened from out of the URL, so a view that wraps it passes only `{card, mutation}`.
-
-## The card kit is a contract
-
-A runtime export of `@danxbot/card-kit@1`, and its parameters, is never removed or changed in place; the keys of the exported data types follow the Versioning section below. A breaking change is `@danxbot/card-kit@2`, served beside `@1` until no approved plugin revision needs it. A plugin's manifest records the majors it was built against, and the app refuses to run a revision built for a major it no longer serves.
-
-## `danx-plugin publish`
-
-Not available yet: it refuses with an error until the plugin upload route ships in the next release of this SDK.
-
-## Versioning
-
-The SDK stays 0.x until the shapes behind the card kit's data types settle: phase 1 of DX-4679 (card types as rows) changes `IssueViewV2.type`, and DX-5164 (designs on any card) changes the design fields. Until then the declarations may change between 0.x releases; the kit's runtime exports follow the `@danxbot/card-kit@1` rule above.
+# @danxbot/plugin-sdk
+
+Build a 50 Arms **card-type plugin**: a small React bundle that gives a card type its own card view (`CardView`) and/or card-list view (`CardListView`), loaded into 50 Arms' own page with `import()`.
+
+A plugin does not bundle React, `@danxbot/ui` or the card features. The app serves them under fixed import specifiers through an import map, so a plugin shares the app's single React and renders the app's own components:
+
+| Specifier | What it is |
+|---|---|
+| `react`, `react/jsx-runtime`, `react-dom` | The app's React |
+| `@danxbot/ui` | The app's design system |
+| `@danxbot/card-kit@1` | The card features: data hooks, card regions (`StandardCardPage`, `EditableTitle`, `ChecklistsSection`, ...), `CardFace`, `CardBoard` |
+
+The live list and each library's major version is `GET /api/plugin-runtime`.
+
+## Set up a plugin
+
+`package.json`: depend on `@danxbot/plugin-sdk` and install its peers: `vite`, `react`, `@types/react`, `@danxbot/ui` and `react-router` (types only: the app serves the real ones; the kit's declarations import them).
+
+`vite.config.ts`:
+
+```ts
+import { defineConfig } from "vite";
+import { danxPlugin } from "@danxbot/plugin-sdk/vite";
+
+export default defineConfig({ plugins: [danxPlugin()] });
+```
+
+`tsconfig.json`: add `"types": ["@danxbot/plugin-sdk/card-kit"]`: the kit's declarations. They are self-contained (they import only `react`, `@danxbot/ui` and `react-router`) and the specifier is not a package, so TypeScript reads them as ambient types.
+
+`src/index.tsx` exports `CardView` and/or `CardListView`:
+
+```tsx
+import { StandardCardPage, type CardViewProps } from "@danxbot/card-kit@1";
+
+export function CardView({ card, mutation }: CardViewProps) {
+  return <StandardCardPage card={card} mutation={mutation} />;
+}
+```
+
+`vite build` writes the plugin to `dist/`: `index.js` (the entry), `chunks/` for code splitting, `index.css`, source maps, and `danx-plugin.json`, the manifest listing every file with its size and sha256 and the runtime majors the plugin was built against.
+
+The build refuses to bundle a copy of React, React DOM, `@danxbot/ui` or `react-router`: import only the specifiers above. For routing, use the kit's `Link` and `useNavigate`; `StandardCardPage` reads the plan the page was opened from out of the URL, so a view that wraps it passes only `{card, mutation}`.
+
+## The card kit is a contract
+
+A runtime export of `@danxbot/card-kit@1`, and its parameters, is never removed or changed in place; the keys of the exported data types follow the Versioning section below. A breaking change is `@danxbot/card-kit@2`, served beside `@1` until no approved plugin revision needs it. A plugin's manifest records the majors it was built against, and the app refuses to run a revision built for a major it no longer serves.
+
+## Publish a revision
+
+```
+DANXBOT_DASHBOARD_URL=https://<your dashboard> DANXBOT_API_KEY=<a key from your own account>   npx danx-plugin publish --plugin <key> --note "what changed" [--dir <project>] [--name "Display name"]
+```
+
+`publish` runs the project's own `npm run build`, archives the source (inside a git repo: the tracked files plus untracked ones git does not ignore; otherwise what the top-level `.gitignore` leaves, minus `node_modules`, `.git` and a top-level `dist`; a lockfile is required, so the download builds as is) and uploads both as a new revision of the plugin `<key>`, creating the plugin on its first publish. It prints the revision number and the Settings > Plugins link where a team admin approves it. `.env*` files are never archived, in or out of git. Inside git, a git failure (git missing, a dubious-ownership refusal) stops the publish with git's message; only "not a git repository" means outside git, where the top-level `.gitignore` is honoured (`*`, `?`, `**`, anchoring and trailing `/`; a `!` negation is refused). A blank note is refused first, before the build, the archive or any request. The dashboard validates the upload; a refusal prints its named reason.
+
+The same flow is exported for tools as `@danxbot/plugin-sdk/publish` (`buildPlugin`, `archiveSource`, `uploadRevision`, `fetchTransport`): the dashboard MCP's `plugin_publish` tool runs it for agents.
+
+## Versioning
+
+The SDK stays 0.x until the shapes behind the card kit's data types settle: phase 1 of DX-4679 (card types as rows) changes `IssueViewV2.type`, and DX-5164 (designs on any card) changes the design fields. Until then the declarations may change between 0.x releases; the kit's runtime exports follow the `@danxbot/card-kit@1` rule above.