@tappify/cli 1.3.2 → 1.5.0

package/package.json

@@ -1,17 +1,26 @@
 {
   "name": "@tappify/cli",
-  "version": "1.3.2",
+  "version": "1.5.0",
   "description": "Tappify CLI - Command line interface for managing deployments and more",
   "author": "Tappify Team",
   "private": false,
   "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
   "bin": {
     "tappify": "./bin/tappify"
   },
   "files": [
     "dist",
-    "bin"
+    "bin",
+    "templates"
   ],
+  "pkg": {
+    "assets": [
+      "templates/**/*"
+    ]
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/tappify-dev/cli.git"
@@ -30,8 +39,8 @@
   "scripts": {
     "build": "nest build && tsc-alias && npm run copy-bin",
     "copy-bin": "mkdir -p bin && cp scripts/tappify bin/tappify && chmod +x bin/tappify",
-    "format": "prettier --write \"src/**/*.ts\" \"*.{json,md}\"",
-    "format:check": "prettier --check \"src/**/*.ts\" \"*.{json,md}\"",
+    "format": "prettier --write \"src/**/*.ts\" \"scripts/**/*.mjs\" \"*.{json,md}\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"scripts/**/*.mjs\" \"*.{json,md}\"",
     "start": "nest start",
     "start:dev": "nest start --watch",
     "start:debug": "nest start --debug --watch",
@@ -39,27 +48,39 @@
     "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
     "test": "jest --passWithNoTests --coverage",
     "test:watch": "jest --watch",
+    "test:codegen": "NODE_OPTIONS=--experimental-vm-modules jest probe.spec --testPathIgnorePatterns=/node_modules/",
     "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
     "prepare": "husky",
     "commit": "cz",
     "prepublishOnly": "npm run build && npm test",
     "release:manual": "./scripts/prepare-release.sh",
     "spellcheck": "cspell \"src/**/*.ts\" \"test/**/*.ts\" \"*.{json,md,yml}\" \".github/**/*.yml\"",
-    "semantic-release": "semantic-release"
+    "semantic-release": "semantic-release",
+    "bundle": "node scripts/bundle.mjs",
+    "build:cli-reference": "node scripts/build-cli-reference.mjs",
+    "sync:starter": "ts-node scripts/sync-starter.ts",
+    "build:binaries": "pnpm build && pnpm bundle && pkg dist/bundle/main.cjs --no-bytecode --public --targets node24-macos-x64,node24-macos-arm64,node24-linux-x64,node24-linux-arm64,node24-win-x64,node24-win-arm64 --out-path dist-bin",
+    "check:release-assets": "node scripts/check-release-assets.cjs"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "@nestjs/common": "^11.1.15",
     "@nestjs/core": "^11.1.15",
     "@nestjs/platform-express": "^11.1.15",
+    "@tappify/extension-sdk": "^2.0.0",
     "archiver": "^7.0.1",
     "chalk": "^5.6.2",
+    "chokidar": "^4.0.3",
     "conf": "^15.1.0",
     "form-data": "^4.0.5",
     "nest-commander": "^3.20.1",
+    "node-pty": "^1.1.0",
     "open": "^11.0.0",
     "ora": "^9.3.0",
     "reflect-metadata": "^0.2.2",
-    "rxjs": "^7.8.2"
+    "rxjs": "^7.8.2",
+    "semver": "^7.8.5",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@commitlint/cli": "^20.4.3",
@@ -79,11 +100,14 @@
     "@types/express": "^5.0.6",
     "@types/jest": "^30.0.0",
     "@types/node": "^25.3.3",
+    "@types/semver": "^7.8.0",
     "@types/supertest": "^7.2.0",
+    "@yao-pkg/pkg": "^6.21.0",
     "commitizen": "^4.3.1",
     "conventional-changelog-conventionalcommits": "^9.3.0",
     "cspell": "^9.7.0",
     "cz-conventional-changelog": "^3.3.0",
+    "esbuild": "^0.28.1",
     "eslint": "^10.0.2",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.5",
@@ -112,6 +136,10 @@
     ],
     "rootDir": "src",
     "testRegex": ".*\\.spec\\.ts$",
+    "testPathIgnorePatterns": [
+      "/node_modules/",
+      "\\.probe\\.spec\\.ts$"
+    ],
     "transform": {
       "^.+\\.(t|j)s$": [
         "ts-jest",
@@ -119,7 +147,15 @@
           "tsconfig": {
             "module": "commonjs",
             "moduleResolution": "node10",
-            "resolvePackageJsonExports": false
+            "resolvePackageJsonExports": false,
+            "paths": {
+              "@/*": [
+                "src/*"
+              ],
+              "@modelcontextprotocol/sdk/*": [
+                "node_modules/@modelcontextprotocol/sdk/dist/esm/*"
+              ]
+            }
           }
         }
       ]

package/templates/contributions/action/schemas/__file__.input.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "__Name__Input",
+  "type": "object",
+  "properties": {
+    "target": {
+      "type": "string",
+      "title": "Target",
+      "description": "Replace this with what the assistant needs to know"
+    }
+  },
+  "required": ["target"],
+  "additionalProperties": false
+}

package/templates/contributions/action/server/actions/__file__.ts

@@ -0,0 +1,8 @@
+import type { ActionInput } from '@tappify/extension-sdk';
+import type { TappifyRequest } from '@tappify/extension-sdk/server';
+
+export function __camel__(request: TappifyRequest<ActionInput<'__name__'>>) {
+  const { target } = request.input;
+
+  return { ok: true, target };
+}

package/templates/contributions/connector/server/metrics.ts

@@ -0,0 +1,19 @@
+import type {
+  MetricsInput,
+  MetricsResponse,
+  TappifyRequest,
+} from '@tappify/extension-sdk/server';
+
+export function metrics(
+  request: TappifyRequest<MetricsInput>,
+): MetricsResponse {
+  return {
+    series: [
+      {
+        metric: 'sessions',
+        unit: 'count',
+        points: [[request.input.from, 0]],
+      },
+    ],
+  };
+}

package/templates/contributions/context/server/context/__file__.ts

@@ -0,0 +1,10 @@
+import type {
+  ContextBlock,
+  TappifyRequest,
+} from '@tappify/extension-sdk/server';
+
+export function __camel__(request: TappifyRequest<undefined>): ContextBlock {
+  return {
+    summary: `Nothing to add for ${request.context.projectId} yet.`,
+  };
+}

package/templates/contributions/knowledge/knowledge/__file__.md

@@ -0,0 +1,6 @@
+# __title__
+
+Write what the assistant should know about this extension's numbers here. Keep
+it factual: definitions, units, time zones, and the mistakes people make when
+reading them. The assistant cites this file, so a sentence you would not sign
+does not belong in it.

package/templates/contributions/mention/server/mentions/__file__.ts

@@ -0,0 +1,10 @@
+import type {
+  MentionItems,
+  TappifyRequest,
+} from '@tappify/extension-sdk/server';
+
+export function __camel__(
+  _request: TappifyRequest<{ q: string }>,
+): MentionItems {
+  return { items: [{ id: 'example', label: 'Example' }] };
+}

package/templates/contributions/page/src/pages/__file__.tsx

@@ -0,0 +1,21 @@
+import {
+  TapEmptyState,
+  TapPageHeader,
+  useTapParams,
+  type TapPageProps,
+} from '@tappify/extension-sdk';
+import '@tappify/extension-sdk/styles.css';
+
+export default function __Name__(_props: TapPageProps) {
+  const params = useTapParams();
+
+  return (
+    <div className="tap-stack">
+      <TapPageHeader title="__title__" description="What this page is for." />
+      <TapEmptyState
+        title="Nothing here yet"
+        description={`Route parameters: ${JSON.stringify(params)}`}
+      />
+    </div>
+  );
+}

package/templates/contributions/page/test/__file__.test.tsx

@@ -0,0 +1,12 @@
+import { renderWithTap } from '@tappify/extension-sdk/testing';
+import { screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import __Name__ from '../src/pages/__file__';
+
+describe('the __title__ page', () => {
+  it('renders its header', () => {
+    renderWithTap(<__Name__ params={{}} />, { scopes: ['ui:render'] });
+
+    expect(screen.getByText('__title__')).toBeInTheDocument();
+  });
+});

package/templates/contributions/procedure/schemas/__file__.input.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "__Name__Input",
+  "type": "object",
+  "properties": {
+    "days": {
+      "type": "number",
+      "description": "How many days the caller is asking about"
+    }
+  },
+  "required": ["days"],
+  "additionalProperties": false
+}

package/templates/contributions/procedure/schemas/__file__.output.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "__Name__Output",
+  "type": "object",
+  "properties": {
+    "value": {
+      "type": "number",
+      "description": "Replace this with what your server answers"
+    }
+  },
+  "required": ["value"],
+  "additionalProperties": false
+}

package/templates/contributions/procedure/server/procedures/__file__.ts

@@ -0,0 +1,13 @@
+import type {
+  TapProcedureInput,
+  TapProcedureOutput,
+} from '@tappify/extension-sdk';
+import type { TappifyRequest } from '@tappify/extension-sdk/server';
+
+export function __camel__(
+  request: TappifyRequest<TapProcedureInput<'__name__'>>,
+): TapProcedureOutput<'__name__'> {
+  const { days } = request.input;
+
+  return { value: days };
+}

package/templates/contributions/prompt/schemas/__file__.input.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "__Name__Input",
+  "type": "object",
+  "properties": {
+    "range": {
+      "type": "string",
+      "title": "Range",
+      "description": "What the owner fills in before the prompt is sent"
+    }
+  },
+  "required": ["range"],
+  "additionalProperties": false
+}

package/templates/contributions/row-action/src/row-actions/__file__.tsx

@@ -0,0 +1,20 @@
+import {
+  TapButton,
+  TapCard,
+  useTap,
+  type TapRowActionProps,
+} from '@tappify/extension-sdk';
+import '@tappify/extension-sdk/styles.css';
+
+export default function __Name__({ row }: TapRowActionProps) {
+  const tap = useTap();
+
+  return (
+    <TapCard title="__title__">
+      <pre>{JSON.stringify(row, null, 2)}</pre>
+      <TapButton onClick={() => tap.ui.toast('Handled.', 'success')}>
+        Do it
+      </TapButton>
+    </TapCard>
+  );
+}

package/templates/contributions/row-action/test/__file__.test.tsx

@@ -0,0 +1,17 @@
+import { renderWithTap } from '@tappify/extension-sdk/testing';
+import { screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it } from 'vitest';
+import __Name__ from '../src/row-actions/__file__';
+
+describe('the __title__ row action', () => {
+  it('toasts when the owner runs it', async () => {
+    const { mock } = renderWithTap(<__Name__ row={{ id: '1' }} />, {
+      scopes: ['ui:render'],
+    });
+
+    await userEvent.click(screen.getByRole('button', { name: 'Do it' }));
+
+    expect(mock).toHaveToasted('Handled.');
+  });
+});

package/templates/contributions/settings/schemas/settings.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Settings",
+  "type": "object",
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "title": "Enabled",
+      "description": "Turn this extension's work on for the project"
+    }
+  },
+  "required": ["enabled"],
+  "additionalProperties": false
+}

package/templates/contributions/settings/src/settings.tsx

@@ -0,0 +1,24 @@
+import {
+  TapForm,
+  TapPageHeader,
+  type TapSettingsProps,
+} from '@tappify/extension-sdk';
+import '@tappify/extension-sdk/styles.css';
+import schema from '../schemas/settings.json';
+
+export default function Settings({ values, onChange }: TapSettingsProps) {
+  return (
+    <div className="tap-stack">
+      <TapPageHeader
+        title="__title__"
+        description="These values reach your server as documents.settings on every call."
+      />
+      <TapForm
+        schema={schema}
+        value={values}
+        submitLabel="Save"
+        onSubmit={next => onChange(next)}
+      />
+    </div>
+  );
+}

package/templates/contributions/settings/test/settings.test.tsx

@@ -0,0 +1,12 @@
+import { renderWithTap } from '@tappify/extension-sdk/testing';
+import { screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import Settings from '../src/settings';
+
+describe('the settings panel', () => {
+  it('renders one control per schema field', () => {
+    renderWithTap(<Settings values={{ enabled: true }} onChange={vi.fn()} />);
+
+    expect(screen.getByLabelText('Enabled')).toBeInTheDocument();
+  });
+});

package/templates/contributions/skill/skills/__file__.md

@@ -0,0 +1,14 @@
+# __title__
+
+Write the steps the assistant should follow when this skill applies. Name the
+tools it may call and the order it should call them in. Keep it under 4,000
+words; anything longer is a sign the skill is two skills.
+
+## When to use this
+
+Describe the question or situation that should load this skill.
+
+## Steps
+
+1. Replace this with the first step.
+2. Replace this with the second step.

package/templates/contributions/storage/schemas/__file__.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "__Name__",
+  "type": "object",
+  "properties": {
+    "note": {
+      "type": "string",
+      "title": "Note",
+      "description": "Replace this with the fields your document holds"
+    }
+  },
+  "required": ["note"],
+  "additionalProperties": false
+}

package/templates/contributions/tab/src/tabs/__file__.tsx

@@ -0,0 +1,21 @@
+import {
+  TapEmptyState,
+  TapPageHeader,
+  type TapTabProps,
+} from '@tappify/extension-sdk';
+import '@tappify/extension-sdk/styles.css';
+
+export default function __Name__(_props: TapTabProps) {
+  return (
+    <div className="tap-stack">
+      <TapPageHeader
+        title="__title__"
+        description="What this tab shows the owner."
+      />
+      <TapEmptyState
+        title="Nothing here yet"
+        description="Replace this with the content your tab shows."
+      />
+    </div>
+  );
+}

package/templates/contributions/tab/test/__file__.test.tsx

@@ -0,0 +1,12 @@
+import { renderWithTap } from '@tappify/extension-sdk/testing';
+import { screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import __Name__ from '../src/tabs/__file__';
+
+describe('the __title__ tab', () => {
+  it('renders its header', () => {
+    renderWithTap(<__Name__ />, { scopes: ['ui:render'] });
+
+    expect(screen.getByText('__title__')).toBeInTheDocument();
+  });
+});

package/templates/contributions/tool/schemas/__file__.input.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "__Name__Input",
+  "type": "object",
+  "properties": {
+    "target": {
+      "type": "string",
+      "title": "Target",
+      "description": "Replace this with what the assistant needs to know"
+    }
+  },
+  "required": ["target"],
+  "additionalProperties": false
+}

package/templates/contributions/tool/server/tools/__file__.ts

@@ -0,0 +1,8 @@
+import type { ToolInput } from '@tappify/extension-sdk';
+import type { TappifyRequest } from '@tappify/extension-sdk/server';
+
+export function __camel__(request: TappifyRequest<ToolInput<'__name__'>>) {
+  const { target } = request.input;
+
+  return { value: target };
+}

package/templates/contributions/webhook/schemas/__file__.payload.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "__Name__Payload",
+  "type": "object",
+  "properties": {
+    "why": {
+      "type": "string",
+      "description": "One sentence the owner reads on the alert or banner"
+    }
+  },
+  "required": ["why"],
+  "additionalProperties": false
+}

package/templates/contributions/widget/src/widgets/__file__.tsx

@@ -0,0 +1,48 @@
+import {
+  TapCard,
+  TapErrorState,
+  TapSkeleton,
+  TapStat,
+  useTap,
+  useTapFilters,
+  useTapQuery,
+  type TapSeriesPoint,
+  type TapWidgetProps,
+} from '@tappify/extension-sdk';
+import '@tappify/extension-sdk/styles.css';
+
+function total(points: TapSeriesPoint[]): number {
+  return points.reduce((sum, point) => sum + point.value, 0);
+}
+
+export default function __Name__(_props: TapWidgetProps) {
+  const tap = useTap();
+  const filters = useTapFilters();
+
+  const downloads = useTapQuery({
+    kind: 'series',
+    metric: 'downloads',
+    range: filters.range,
+  });
+
+  return (
+    <TapCard title="__title__">
+      {downloads.isLoading && <TapSkeleton lines={2} />}
+
+      {downloads.error !== null && (
+        <TapErrorState
+          title="__title__ did not load"
+          description={downloads.error.message}
+          onRetry={() => downloads.refetch()}
+        />
+      )}
+
+      {downloads.error === null && downloads.data !== undefined && (
+        <TapStat
+          label="Downloads"
+          value={tap.format.number(total(downloads.data.points))}
+        />
+      )}
+    </TapCard>
+  );
+}

package/templates/contributions/widget/test/__file__.test.tsx

@@ -0,0 +1,16 @@
+import { renderWithTap } from '@tappify/extension-sdk/testing';
+import { screen, waitFor } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import __Name__ from '../src/widgets/__file__';
+
+describe('the __title__ widget', () => {
+  it('renders the total for the range the page is showing', async () => {
+    renderWithTap(<__Name__ config={{}} />, {
+      scopes: ['ui:render', 'analytics:read'],
+    });
+
+    await waitFor(() =>
+      expect(screen.getByText('__title__')).toBeInTheDocument(),
+    );
+  });
+});

package/templates/contributions/work/server/work.ts

@@ -0,0 +1,14 @@
+import type { TappifyRequest } from '@tappify/extension-sdk/server';
+
+type WorkRequest = TappifyRequest<Record<string, unknown>>;
+
+export const work = {
+  list_containers: () => ({
+    containers: [{ id: 'example', label: 'Example project' }],
+  }),
+  create: (request: WorkRequest) => ({
+    id: 'example-1',
+    url: 'https://example.com/issues/example-1',
+    title: String(request.input.title ?? 'Untitled'),
+  }),
+};

package/templates/starter/README.md

@@ -0,0 +1,75 @@
+# __title__
+
+A Tappify extension that shows a one-line install summary on the Analytics page, remembers how each teammate likes it, and answers its own server for the number.
+
+```bash
+pnpm install
+pnpm dev
+```
+
+`pnpm dev` serves `remoteEntry.js` on http://localhost:5273. Open the extension's Preview page in the developer portal to see the widget, or run `tappify extension dev --live` to mount it on your sandbox project.
+
+```bash
+pnpm typecheck
+pnpm build
+```
+
+`pnpm typecheck` runs `tsc` over the widget, the settings panel, the server and the tests. `pnpm build` writes the bundle Tappify loads, `dist/remoteEntry.js`, alongside `dist/mf-manifest.json`.
+
+## What is here
+
+| Path | What it is |
+| --- | --- |
+| `tappify.extension.json` | The manifest. Every contribution, scope and schema reference lives here |
+| `src/widgets/summary.tsx` | The widget that renders in the `kpi-row` slot on Analytics |
+| `src/settings.tsx` | The settings panel owners see on the per-install page |
+| `src/tappify.d.ts` | Generated types. Run `pnpm types` after changing the manifest; commit the result |
+| `schemas/` | JSON Schemas the manifest points at, for storage, settings and the procedure |
+| `server/handler.ts` | The extension server: one health check and one procedure |
+| `test/` | One test per contribution, plus a server test |
+| `test/matchers.d.ts` | Pulls the Vitest matcher declarations from the SDK and `jest-dom` into the type program |
+
+## The widget
+
+`useTapFilters()` gives the widget the page's date range and platform picker, so both numbers follow the picker with no code of its own. `useTapQuery({ kind: "series", metric: "downloads", range })` reads the project's own analytics from Tappify — that is the `analytics:read` scope the manifest asks for, and dropping the scope turns the query into the error state the widget already renders. `useTapServer("getSummary", input)` posts through the host to the extension server, which means no CORS, no server URL in the browser, and the owner's credentials never leave Tappify. `useTapStorage("preferences")` keeps each teammate's compact toggle in hosted storage, and `tap.data.subscribe("release.shipped")` refreshes the number when a release goes out.
+
+Ask for the scopes you use and no others. This extension queries analytics, renders UI and writes storage, so it declares `analytics:read`, `ui:render` and `storage:write` — and nothing else.
+
+## The server
+
+`server/handler.ts` exports `handlerOptions` and a fetch handler. The same handler deploys two ways:
+
+```bash
+pnpm deploy:worker
+```
+
+deploys `server/worker.ts` to Cloudflare Workers using `wrangler.toml`. The Worker serves the routes at the root, so set `server.baseUrl` in `tappify.extension.json` to `https://__id__-server.<your-subdomain>.workers.dev` — the origin, with no path.
+
+`api/tappify/[...path].ts` is a Vercel function over the same handler. Vercel invokes it at `/api/tappify/…`, so the function passes `basePath: "/api"`; deploy the repository to Vercel and set `server.baseUrl` to `https://<your-app>.vercel.app/api` — the origin **and** the `/api` prefix.
+
+Whichever you pick, Tappify calls `GET <baseUrl>/tappify/health` at publish and every 15 minutes, and `POST <baseUrl>/tappify/procedures/getSummary` whenever the widget asks.
+
+## Changing the manifest
+
+```bash
+pnpm types
+```
+
+rewrites `src/tappify.d.ts` from the manifest and its schemas. `tap.storage.preferences`, `tap.server.getSummary`, `TapSettingsProps["values"]` and the telemetry event name are all typed from that file, so a schema change that breaks a component is a type error rather than a runtime surprise. `pnpm types` runs `tappify extension types`, which types the host event payloads too.
+
+## Tests
+
+```bash
+pnpm test
+```
+
+`renderWithTap` mounts a component against an in-memory bridge with the same fixtures the portal preview uses. `createTestClient` drives the server the way Tappify does, with a signed token, so the procedure is tested end to end without a running Tappify.
+
+## Publishing
+
+```bash
+tappify extension doctor
+tappify extension publish --notes "First release"
+```
+
+`doctor` runs the same checks the platform runs at publish, including this repository's test script.