@ekanos/cli 0.1.0

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@ekanos/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "The Ekanos partner toolchain CLI: scaffold, validate, and test a Fusion integration against the published @ekanos packages. Agent-native — every verb speaks JSON with a stable exit-code taxonomy.",
+  "license": "MIT",
+  "bugs": {
+    "email": "npm@govastly.com"
+  },
+  "keywords": [
+    "ekanos",
+    "fusion",
+    "integration",
+    "cli"
+  ],
+  "bin": {
+    "ekanos": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ekanos/integration-schema": "0.1.2",
+    "esbuild": "0.28.1"
+  },
+  "peerDependencies": {
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@kit/eslint-config": "0.2.0",
+    "@kit/prettier-config": "0.1.0",
+    "@kit/tsconfig": "0.1.0",
+    "@types/node": "25.0.1",
+    "typescript": "^5.9.3",
+    "vitest": "4.1.10",
+    "zod": "3.25.76"
+  },
+  "prettier": "@kit/prettier-config",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/rewrite-esm-specifiers.mjs",
+    "clean": "git clean -xdf .turbo node_modules dist",
+    "format": "prettier --check \"**/*.{ts,tsx}\"",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --config vitest.config.ts"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}

package/templates/ekanos.json.tmpl

@@ -0,0 +1,4 @@
+{
+  "slug": "__SLUG__",
+  "entry": "src/integration.ts"
+}

package/templates/gitignore.tmpl

@@ -0,0 +1,12 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+*.tsbuildinfo
+
+# Ekanos dev harness (scaffolded on demand; keep only your registry)
+.ekanos/
+
+# Logs
+*.log

package/templates/harness/app/[slug]/activation/page.tsx.tmpl

@@ -0,0 +1 @@
+export { ActivationPage as default } from '@ekanos/harness/routes';

package/templates/harness/app/[slug]/layout.tsx.tmpl

@@ -0,0 +1 @@
+export { IntegrationLayout as default } from '@ekanos/harness/routes';

package/templates/harness/app/[slug]/tile/page.tsx.tmpl

@@ -0,0 +1 @@
+export { TilePage as default } from '@ekanos/harness/routes';

package/templates/harness/app/[slug]/triggers/page.tsx.tmpl

@@ -0,0 +1 @@
+export { TriggersPage as default } from '@ekanos/harness/routes';

package/templates/harness/app/[slug]/widgets/[widgetId]/page.tsx.tmpl

@@ -0,0 +1 @@
+export { SingleWidgetPage as default } from '@ekanos/harness/routes';

package/templates/harness/app/[slug]/widgets/page.tsx.tmpl

@@ -0,0 +1 @@
+export { WidgetsPage as default } from '@ekanos/harness/routes';

package/templates/harness/app/harness-shell.tsx.tmpl

@@ -0,0 +1,9 @@
+'use client';
+
+import { RootLayout } from '@ekanos/harness/app';
+
+import { harnessIntegrations } from '../../../harness.config';
+
+export default function HarnessShell(props: { children: React.ReactNode }) {
+  return <RootLayout integrations={harnessIntegrations} {...props} />;
+}

package/templates/harness/app/layout.tsx.tmpl

@@ -0,0 +1,4 @@
+import '../styles/globals.css';
+
+export { harnessMetadata as metadata } from '@ekanos/harness/app';
+export { default } from './harness-shell';

package/templates/harness/app/page.tsx.tmpl

@@ -0,0 +1,7 @@
+import { IndexPage } from '@ekanos/harness/app';
+
+import { harnessIntegrations } from '../../../harness.config';
+
+export default function HarnessIndex() {
+  return <IndexPage integrations={harnessIntegrations} />;
+}

package/templates/harness/next.config.mjs.tmpl

@@ -0,0 +1,46 @@
+// Generated by `ekanos dev`. Owned by @ekanos/cli — every file under
+// .ekanos/ is regenerated on each run, so edits here are lost. Change your
+// integration or harness.config.ts instead.
+import { fileURLToPath } from 'node:url';
+
+/**
+ * The shell lives two directories below your project root and has no
+ * node_modules of its own; `next`, `react` and `@ekanos/harness` all resolve
+ * upward into yours. Pointing Next at that root stops it inferring a different
+ * one and keeps file watching over your integration source.
+ */
+const projectRoot = fileURLToPath(new URL('../../', import.meta.url));
+
+/** @type {import('next').NextConfig} */
+const config = {
+  reactStrictMode: true,
+  // Everything else @ekanos ships is pre-bundled dist that Next can consume
+  // as-is. `@ekanos/harness` is the exception: its dist is compiled per file
+  // rather than bundled, and `RootLayout` reaches `next/font/google` — a
+  // build-time macro that only runs on code Next itself compiles. Drop this
+  // and the harness renders in the system font stack, with no error.
+  transpilePackages: ['@ekanos/harness'],
+  turbopack: {
+    root: projectRoot,
+    resolveAlias: {
+      // A widget written for the real Fusion host imports
+      // `useTeamAccountWorkspace()` to read `account.slug`. That module
+      // reaches Supabase, which the harness deliberately does not have, so
+      // this points the specifier at the shape-identical mock @ekanos/harness
+      // ships. It is what lets your widget source run here unmodified.
+      //
+      // The target is a bare specifier rather than a path, so it resolves
+      // through the package's own exports map and holds however your package
+      // manager laid out node_modules.
+      //
+      // Its type side is types/team-accounts.d.ts, generated next to this
+      // file. Change one without the other and the harness runs but stops
+      // type-checking — which is why both are generated and neither is
+      // yours to edit.
+      '@kit/team-accounts/hooks/use-team-account-workspace':
+        '@ekanos/harness/mocks/team-account-workspace',
+    },
+  },
+};
+
+export default config;

package/templates/harness/package.json.tmpl

@@ -0,0 +1,11 @@
+{
+  "//": "Generated by `ekanos dev`. Owned by @ekanos/cli — edits are overwritten. Declares no dependencies on purpose: next, react and @ekanos/harness all resolve upward into your project's node_modules, so this runs your Next and your React rather than installing a second copy of each.",
+  "name": "__SLUG__-harness",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev --port 3100",
+    "build": "next build"
+  }
+}

package/templates/harness/postcss.config.mjs.tmpl

@@ -0,0 +1,6 @@
+// Generated by `ekanos dev`. Owned by @ekanos/cli — edits are overwritten.
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};

package/templates/harness/styles/globals.css.tmpl

@@ -0,0 +1,33 @@
+/*
+ * Generated by `ekanos dev`. Owned by @ekanos/cli — edits are overwritten.
+ *
+ * One import for the harness itself, then the `@source` globs covering code
+ * YOU own. Everything the harness chrome renders — its own components,
+ * `@ekanos/ui`, `@ekanos/sdk` — is already accounted for inside
+ * `@ekanos/harness/styles.css`, so nothing about the harness needs a glob here.
+ */
+@import '@ekanos/harness/styles.css';
+
+/*
+ * Your integration source, and the registry that lists it. A missing @source
+ * path is a no-op and Tailwind never scans node_modules unless told to, so a
+ * glob that matches nothing costs you a completely unstyled widget with no
+ * build error at all.
+ *
+ * This file is regenerated on every `ekanos dev`, so do not add lines here —
+ * they would be erased. If your integration lives somewhere these globs miss,
+ * add it to "sourceGlobs" in ekanos.json and it appears at the bottom of this
+ * file.
+ */
+@source '../../../harness.config.ts';
+@source '../../../{src,app,lib,components,integrations,packages}/**/*.{ts,tsx}';
+
+/*
+ * Tailwind never scans node_modules unless told to, so this points it at the
+ * harness's own compiled output. `@ekanos/harness/styles.css` already covers
+ * itself, making this a deliberate duplicate: a repeated @source costs
+ * nothing, and a missing one costs you a page with no styling and no error to
+ * explain it.
+ */
+@source '../../../node_modules/@ekanos/harness/dist/**/*.js';
+__SOURCE_GLOBS__

package/templates/harness/tsconfig.json.tmpl

@@ -0,0 +1,31 @@
+{
+  "//": "Generated by `ekanos dev`. Edits here are overwritten on the next run — change your integration or harness.config.ts instead. Imports are spelled relative rather than through a `~/*` alias because this directory sits two levels below your project root, so one alias would have to mean two different roots. The team-accounts mock is typed by types/team-accounts.d.ts rather than a `paths` entry, so it resolves through the package export map. There is no `baseUrl`: TypeScript 7 removed it, and it is not needed here.",
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "allowJs": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "tsBuildInfoFile": ".next/cache/tsbuildinfo.json"
+  },
+  "//include": "next build rewrites this file in place if it disagrees, which would fight regeneration on the next `ekanos dev`. These are the values Next asks for, pre-applied: `jsx: react-jsx` for the automatic runtime, and both generated type roots.",
+  "include": [
+    "next-env.d.ts",
+    "types/**/*.d.ts",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    "../../harness.config.ts"
+  ],
+  "exclude": ["node_modules", ".next"]
+}

package/templates/harness/types/team-accounts.d.ts.tmpl

@@ -0,0 +1,16 @@
+/*
+ * Generated by `ekanos dev`. Owned by @ekanos/cli — edits are overwritten.
+ *
+ * Type side of the `next.config.mjs` resolveAlias. Widgets written for the
+ * real host import `@kit/team-accounts/hooks/use-team-account-workspace`,
+ * which does not exist here; the harness ships a shape-identical mock.
+ *
+ * This goes through the package's PUBLIC export map rather than a literal
+ * path into its `dist/`, so a harness release is free to move the file as
+ * long as it keeps the exports entry — which is what an exports map is for.
+ * A `paths` entry cannot do that: TypeScript resolves a `paths` target as a
+ * file path, not as a module specifier, so it would have to name `dist/`.
+ */
+declare module '@kit/team-accounts/hooks/use-team-account-workspace' {
+  export * from '@ekanos/harness/mocks/team-account-workspace';
+}

package/templates/harness.config.entry.ts.tmpl

@@ -0,0 +1,65 @@
+  {
+    slug: __IDENT__.slug,
+    name: __IDENT__.name,
+    description: __IDENT__.description,
+
+    // Powers the Triggers surface from your declared webhooks and schedules.
+    definition: asHarnessDefinition(__IDENT__),
+
+    // Recorded HTTP exchanges, per variant. This is how you give the harness
+    // something to answer with: it issues no requests of its own, and an
+    // unrecorded URL is refused by name rather than silently missing.
+    //
+    // Declared here rather than on a widget because a URL is not owned by one
+    // — the same request may answer two widgets and a webhook handler.
+    //
+    // Uncomment and point it at a route of yours:
+    //
+    // fixtures: {
+    //   default: [
+    //     {
+    //       request: 'GET /api/integrations/__SLUG__/things',
+    //       response: { things: [{ id: 1, name: 'First' }] },
+    //     },
+    //   ],
+    //   // `error` is not a special code path — it is ordinary fixtures with
+    //   // error statuses, so you exercise the real failure branch.
+    //   error: [{ request: 'GET /api/integrations/__SLUG__/things', status: 503 }],
+    // },
+    //
+    // That is a HOST route, which is what most widgets actually call: the
+    // vendor credential lives server-side, so the browser talks to your route
+    // and your route talks to the vendor. Path-only under `/api` resolves
+    // against the harness's own origin, so it needs no configuration.
+    //
+    // Recording a vendor call directly? Use the absolute form —
+    // `'GET https://api.example.com/v1/things'`. The path-only shorthand
+    // outside `/api` resolves against the single origin in
+    // `defineIntegration({ egress })`, and this starter declares none.
+    // Every widget your definition declares. Deriving the list is just a
+    // starting point — replace this with explicit entries importing your
+    // widget components directly and the cast below goes away:
+    // `defineIntegration` erases a component to a structural
+    // `ComponentReference` so the schema package can stay free of React, and
+    // only the author knows the real prop type.
+    //
+    // A widget can also carry `seeds` — query-key values written straight into
+    // the react-query cache, so it paints with no request at all. That is the
+    // fast path, not the default: it works only if your data layer is
+    // react-query, and it addresses data by query key rather than by what the
+    // vendor actually returns. Prefer `fixtures` above; reach for `seeds` when
+    // you want one specific widget to skip the request entirely.
+    widgets: (__IDENT__.components?.widgets ?? []).map(
+      (widget): HarnessWidget => ({
+        id: widget.id,
+        title: widget.name,
+        component: widget.component as HarnessWidget['component'],
+        width: 'half',
+      }),
+    ),
+
+    // Uncomment as you build them out:
+    // tile: YourMarketplaceTile,
+    // activationForm: YourActivationForm,
+    // triggerMocks: { secrets: { account: { apiKey: 'test-key' } } },
+  },

package/templates/harness.config.ts.tmpl

@@ -0,0 +1,58 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ *  THE HARNESS REGISTRY — the one harness file you own.
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * `ekanos dev` writes this once and then never touches it again: it is yours,
+ * it is git-tracked, and the generated shell under `.ekanos/` reads it. That
+ * shell IS regenerated on every run, and `@ekanos/harness` is an ordinary
+ * dependency, so a harness bugfix reaches you through `pnpm up` with no edit
+ * to any file you own.
+ *
+ * Each entry appears at `/<slug>` with five surfaces wired up: widgets in the
+ * real dashboard grid, a single-widget page, the marketplace tile, the
+ * activation form, and Triggers (declared webhooks/schedules, executed
+ * locally against a mock context).
+ *
+ * The `fixtures` are the part that matters. The harness issues no requests of
+ * its own, so a surface stays empty until a recorded exchange answers it.
+ * Write them as HTTP — the shape your vendor actually returns — and one
+ * recording feeds every widget and handler that calls the same URL.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ *  ONE CONSTRAINT THIS FILE IMPOSES ON YOUR CODE
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * This module is imported from BOTH a server component (the harness index
+ * page) and a client component (the shell that provides the registry), so
+ * everything reachable from here must be importable in both graphs.
+ *
+ * In practice that means: do not reach into a `'use client'` module for
+ * fixture query keys. It compiles, then fails at request time with
+ *
+ *     Attempted to call <yourKeyFn>() from the server but <yourKeyFn> is on
+ *     the client.
+ *
+ * The fix is to move the query-key builders into a plain module with no
+ * `'use client'` directive and have your hooks import THAT. Your hooks stay
+ * client-only; only the key builders move. This is worth doing regardless —
+ * shared keys that both sides import are how you stop widget `seeds` drifting
+ * away from the hooks they are meant to seed.
+ */
+import { defineHarnessConfig } from '@ekanos/harness/config';
+import {
+  asHarnessDefinition,
+  type HarnessWidget,
+} from '@ekanos/harness/registry';
+
+__INTEGRATION_IMPORTS__
+
+/**
+ * `defineHarnessConfig` is an identity function at runtime, but it is not
+ * decoration: it checks the things TypeScript cannot — that every slug and
+ * widget id survives being a URL segment, and that none of them collide. Those
+ * are the mistakes that produce a blank page or the WRONG page rather than an
+ * error, and this is the one place every entry passes through.
+ */
+export const harnessIntegrations = defineHarnessConfig([
+__INTEGRATION_ENTRIES__]);

package/templates/package.json.tmpl

@@ -0,0 +1,28 @@
+{
+  "name": "__SLUG__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "A Fusion integration built with @ekanos/sdk.",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@ekanos/sdk": "^0.1.0",
+    "@ekanos/ui": "^0.1.0"
+  },
+  "devDependencies": {
+    "@hookform/resolvers": "^5.2.2",
+    "@tanstack/react-query": "^5.101.4",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "next": "^16.0.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "react-hook-form": "^7.68.0",
+    "typescript": "^5.9.3",
+    "vitest": "4.1.10",
+    "zod": "^3.25.76"
+  }
+}

package/templates/src/integration.test.ts.tmpl

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+
+import { createMockContext } from '@ekanos/sdk/testing';
+
+import { integration } from './integration';
+
+describe('__DISPLAY_NAME__ integration', () => {
+  it('declares its slug and at least one widget', () => {
+    expect(integration.slug).toBe('__SLUG__');
+    expect(integration.components?.widgets?.length ?? 0).toBeGreaterThan(0);
+  });
+
+  it('runs get_greeting against a mock context', async () => {
+    // `createMockContext` requires its options object, and `integration` is
+    // required within it — the mock derives the slug, storage schemas and
+    // egress allowlist from your declaration rather than guessing.
+    const ctx = createMockContext({ integration: { slug: '__SLUG__' } });
+    const tool = integration.tools?.find((t) => t.name === 'get_greeting');
+    expect(tool).toBeDefined();
+
+    const result = await tool!.run(ctx as never, { name: 'Ekanos' });
+    expect(result).toEqual({ greeting: 'Hello, Ekanos!' });
+  });
+});

package/templates/src/integration.ts.tmpl

@@ -0,0 +1,83 @@
+/**
+ * Your integration, declared in one object.
+ *
+ * `defineIntegration()` validates this at import time and hands back a
+ * deep-frozen copy. The host re-validates the same object against the same
+ * schema when it registers the package, so a definition `ekanos validate`
+ * accepts is a definition the platform will accept.
+ *
+ * The export MUST be named `integration`.
+ */
+import { createElement } from 'react';
+
+import { defineIntegration } from '@ekanos/sdk/integration';
+
+// A minimal dashboard widget. This starter uses React.createElement so it can
+// live in a .ts file; move it to its own .tsx file and reach for the Widget.*
+// compound API from '@ekanos/sdk/components' when you build something real.
+function HelloWidget() {
+  return createElement(
+    'div',
+    { style: { padding: 16 } },
+    'Hello from __DISPLAY_NAME__',
+  );
+}
+
+export const integration = defineIntegration({
+  slug: '__SLUG__',
+  name: '__DISPLAY_NAME__',
+  description:
+    'A starter __DISPLAY_NAME__ integration scaffolded by @ekanos/cli. Replace this with a real description of what your integration does.',
+  version: '0.1.0',
+
+  capabilities: [
+    {
+      label: 'A first capability',
+      description: 'Describe one thing this integration does for the user.',
+    },
+  ],
+
+  permissions: [
+    {
+      label: 'Read your data',
+      detail: 'Explain exactly what this integration reads, and why.',
+      type: 'read',
+    },
+  ],
+
+  components: {
+    widgets: [
+      {
+        // Widget ids are GLOBAL — the dashboard resolves widget_config rows by
+        // them — so keep the integration slug as the prefix.
+        id: '__SLUG__-hello',
+        name: 'Hello',
+        component: HelloWidget,
+        widgetState: 'active',
+        isCollapsible: true,
+        layouts: {
+          lg: { x: 0, y: 0, w: 4, h: 6 },
+          md: { x: 0, y: 0, w: 4, h: 6 },
+          sm: { x: 0, y: 0, w: 4, h: 6 },
+        },
+      },
+    ],
+  },
+
+  tools: [
+    {
+      name: 'get_greeting',
+      description: 'Return a friendly greeting from __DISPLAY_NAME__.',
+      parameters: {
+        type: 'object',
+        properties: { name: { type: 'string' } },
+        required: [],
+        additionalProperties: false,
+      },
+      run: async (_ctx, args) => {
+        const who = typeof args.name === 'string' ? args.name : 'there';
+        return { greeting: `Hello, ${who}!` };
+      },
+    },
+  ],
+});

package/templates/tsconfig.json.tmpl

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "ES2022"],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src", "harness.config.ts", "vitest.config.ts"],
+  "exclude": ["node_modules", "dist", ".ekanos"]
+}

package/templates/vitest.config.ts.tmpl

@@ -0,0 +1,32 @@
+import { fileURLToPath } from 'node:url';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      // Some @ekanos/sdk client entrypoints transitively import `server-only`,
+      // whose default export throws outside a React Server Component. Point it
+      // at a no-op stub for the Node test process. (Create the stub at
+      // src/__tests__/server-only.stub.ts when you import an SDK client
+      // surface from a tested module.)
+      'server-only': fileURLToPath(
+        new URL('./src/__tests__/server-only.stub.ts', import.meta.url),
+      ),
+    },
+  },
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+    // REQUIRED — do not remove. The published @ekanos/sdk dist imports the
+    // extensionless "next/link"; without inlining the SDK here, vitest cannot
+    // transform and load it, your test files import nothing, and vitest reports
+    // GREEN over zero tests. `ekanos validate` fails the build if this block
+    // is missing.
+    server: {
+      deps: {
+        inline: ['@ekanos/sdk'],
+      },
+    },
+  },
+});