@ekanos/cli 0.16.0 → 0.17.0

package/dist/validate-findings.js

@@ -5,7 +5,7 @@ import { collectDesignFindings } from './design-findings.js';
 import { preconditionError } from './errors.js';
 import { collectIconFindings } from './icon-findings.js';
 import { loadDefinition } from './load-definition.js';
-import { collectDocsFindings, collectHostCompilerRulesFindings, collectProjectFindings, } from './project-checks.js';
+import { collectDocsFindings, collectHostCompilerRulesFindings, collectLintToolingFindings, collectProjectFindings, } from './project-checks.js';
 /**
  * The full findings pass shared by `validate` (which reports them) and
  * `publish` (which refuses to submit on any error-severity finding). One
@@ -61,6 +61,7 @@ export async function collectAllFindings(loaded) {
     // Cross-checks only mean something with more than one definition in hand.
     findings.push(...collectCollisionFindings(definitions));
     findings.push(...collectProjectFindings(loaded.projectDir));
+    findings.push(...collectLintToolingFindings(loaded.projectDir));
     findings.push(...collectDocsFindings(loaded.project, loaded.projectDir));
     findings.push(...collectIconFindings(loaded.projectDir));
     findings.push(...collectDesignFindings(loaded.projectDir));

package/dist/validate-findings.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate-findings.js","sourceRoot":"","sources":["../src/validate-findings.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  DefinitionCollisionInput,\n  Finding,\n} from '@ekanos/integration-schema';\nimport {\n  collectCollisionFindings,\n  collectDefinitionFindings,\n} from '@ekanos/integration-schema';\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport { collectDesignFindings } from './design-findings';\nimport { preconditionError } from './errors';\nimport { collectIconFindings } from './icon-findings';\nimport { loadDefinition } from './load-definition';\nimport type { LoadedProject } from './project';\nimport {\n  collectDocsFindings,\n  collectHostCompilerRulesFindings,\n  collectProjectFindings,\n} from './project-checks';\n\n/**\n * The full findings pass shared by `validate` (which reports them) and\n * `publish` (which refuses to submit on any error-severity finding). One\n * implementation so the publish gate can never drift from what `validate`\n * checks — a project that validates clean is, by construction, a project that\n * publish will accept locally.\n *\n * NOTE on schema skew: an earlier version of this function rewrote the\n * unrecognized-key hint when the project's `@ekanos/integration-schema` was\n * newer than the CLI's (see `schema-skew.ts`). That rewrite was dead code —\n * `assertSchemaNotSkewed` throws PRECONDITION_FAILED before either `validate`\n * or `publish` ever calls this function in that state, so a project-newer\n * finding can never reach here to be rewritten, and the precondition error\n * already names both versions and points at the fix. It was removed rather\n * than kept \"just in case\": if a future caller ever makes validate proceed\n * under skew instead of failing fast, THAT is when a rewrite here becomes\n * necessary again, and it should be reintroduced with a real caller driving\n * it, not tests that fake their own reachability.\n */\nexport async function collectAllFindings(\n  loaded: LoadedProject,\n): Promise<Finding[]> {\n  const findings: Finding[] = [];\n  const definitions: DefinitionCollisionInput[] = [];\n\n  for (const integration of loaded.integrations) {\n    const result = await loadDefinition(\n      integration.entryPath,\n      loaded.projectDir,\n    );\n\n    if (result.ok) {\n      findings.push(\n        ...collectDefinitionFindings(result.definition, {\n          file: integration.entryPath,\n        }),\n      );\n      findings.push(\n        ...collectSlugAgreementFindings(\n          integration,\n          result.definition as { slug?: unknown },\n        ),\n      );\n      findings.push(\n        ...collectVersionAgreementFindings(\n          integration,\n          result.definition as { version?: unknown },\n          loaded.projectDir,\n        ),\n      );\n      findings.push(\n        ...collectOAuthSetupFindings(integration, result.definition),\n      );\n      definitions.push(result.definition as DefinitionCollisionInput);\n      continue;\n    }\n\n    if (result.kind === 'rejected') {\n      // The module loaded but the SDK/schema rejected the definition at import\n      // time — surface it as a validation finding rather than a crash.\n      findings.push({\n        check: 'definition.load',\n        severity: 'error',\n        file: integration.entryPath,\n        message: result.message,\n        hint:\n          'Fix the integration definition so defineIntegration() accepts it, ' +\n          'then re-run validate.',\n      });\n      continue;\n    }\n\n    // A genuine module-load failure is a precondition, not a finding.\n    throw preconditionError(\n      `Could not load the integration definition for \"${integration.slug}\": ` +\n        result.message,\n      'Ensure the entry module and its installed dependencies load under ' +\n        'Node, then re-run validate.',\n    );\n  }\n\n  // Cross-checks only mean something with more than one definition in hand.\n  findings.push(...collectCollisionFindings(definitions));\n  findings.push(...collectProjectFindings(loaded.projectDir));\n  findings.push(...collectDocsFindings(loaded.project, loaded.projectDir));\n  findings.push(...collectIconFindings(loaded.projectDir));\n  findings.push(...collectDesignFindings(loaded.projectDir));\n  findings.push(...collectHostCompilerRulesFindings(loaded.projectDir));\n\n  return findings;\n}\n\n/**\n * `ekanos.json` and the definition each carry a slug, and nothing compared\n * them: a project could declare `something-else` while the definition said\n * `repo-activity` and validate would report `{ ok: true, findings: [] }`.\n *\n * That is the identifier every surface addresses the integration by — the\n * harness route, the product slug, the widget id prefix, the MCP server — so\n * two sources of truth disagreeing is not a style question. It is an error,\n * not a warning, for the same reason a silent default is worse than a loud\n * one: the failure it causes shows up somewhere else entirely.\n */\nfunction collectSlugAgreementFindings(\n  integration: { slug: string; entry: string; entryPath: string },\n  definition: { slug?: unknown },\n): Finding[] {\n  const declared = definition.slug;\n  if (typeof declared !== 'string' || declared === integration.slug) return [];\n\n  return [\n    {\n      check: 'project.slug-agreement',\n      severity: 'error',\n      file: integration.entryPath,\n      message:\n        `ekanos.json declares slug \"${integration.slug}\" for this entry, but ` +\n        `the definition says \"${declared}\". The slug addresses the ` +\n        'integration everywhere — its harness route, its product record, its ' +\n        'widget ids — so the two must agree.',\n      hint:\n        `Change one to match the other: either set \"slug\": \"${declared}\" in ` +\n        `ekanos.json, or pass slug: '${integration.slug}' to ` +\n        'defineIntegration().',\n    },\n  ];\n}\n\n/**\n * `package.json`'s `version` field and the `version` `defineIntegration()`\n * declares are two more independent sources of truth for the same fact —\n * this project shipped weather@0.1.1 with a package.json bump, but the\n * declaration itself still said 0.1.0. Generated seeds embed the\n * DECLARATION's version in their header, so a stale declaration produces a\n * seed that looks stale even though the package itself moved on.\n *\n * WARN, not error, unlike slug agreement: a mismatched version is a quality\n * signal a partner should fix, not a broken cross-reference that breaks\n * something else at runtime, so it must not block `publish`. And a project\n * with no package.json, or a package.json with no `version` field, has\n * nothing to compare the declaration against — skip rather than warn on\n * absence.\n */\nexport function collectVersionAgreementFindings(\n  integration: { slug: string; entry: string; entryPath: string },\n  definition: { version?: unknown },\n  projectDir: string,\n): Finding[] {\n  const declared = definition.version;\n  if (typeof declared !== 'string') return [];\n\n  const manifestPath = path.join(projectDir, 'package.json');\n  if (!fs.existsSync(manifestPath)) return [];\n\n  let manifest: unknown;\n  try {\n    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));\n  } catch {\n    // Malformed package.json is npm's problem to report, not a validate\n    // finding — nothing here can compare against an unparseable manifest.\n    return [];\n  }\n\n  const packageVersion =\n    typeof manifest === 'object' && manifest !== null\n      ? (manifest as { version?: unknown }).version\n      : undefined;\n  if (typeof packageVersion !== 'string' || packageVersion === declared) {\n    return [];\n  }\n\n  return [\n    {\n      check: 'project.version-agreement',\n      severity: 'warn',\n      file: integration.entryPath,\n      message:\n        `package.json declares version \"${packageVersion}\", but the ` +\n        `defineIntegration() declaration for \"${integration.slug}\" still ` +\n        `says \"${declared}\". Generated seed headers embed the ` +\n        \"declaration's version, so a stale declaration ships stale-looking \" +\n        'metadata even though the package itself moved on.',\n      hint:\n        `Update the \"version\" passed to defineIntegration() in ` +\n        `${integration.entryPath} to match package.json's \"${packageVersion}\".`,\n    },\n  ];\n}\n\n/**\n * An OAuth connection with no `setup` steps leaves whoever creates its app —\n * the Source admin (`ekanos apps`) or each team — to work out the provider's\n * console alone. A warning, not an error: the connection works without it.\n */\nexport function collectOAuthSetupFindings(\n  integration: { entryPath: string },\n  definition: unknown,\n): Finding[] {\n  if (typeof definition !== 'object' || definition === null) return [];\n  const { oauth, oauthConnections } = definition as {\n    oauth?: { setup?: unknown; teamApp?: unknown };\n    oauthConnections?: Record<string, { setup?: unknown; teamApp?: unknown }>;\n  };\n\n  type Connection = { setup?: unknown; teamApp?: unknown };\n  const connections: Array<readonly [string, Connection]> = [\n    ...(oauth ? [['oauth', oauth] as const] : []),\n    ...Object.entries(oauthConnections ?? {}).map(\n      ([id, connection]) => [`oauthConnections.${id}`, connection] as const,\n    ),\n  ];\n\n  return connections\n    .filter(([, connection]) => connection.setup === undefined)\n    .map(([where, connection]) => ({\n      check: 'oauth.setup-missing',\n      severity: 'warn' as const,\n      file: integration.entryPath,\n      message:\n        `${where} has no setup steps, so ` +\n        (connection.teamApp\n          ? 'each team creating its app'\n          : \"the Source admin creating the Source's app (ekanos apps set)\") +\n        \" gets no guidance in the provider's console.\",\n      hint:\n        `Add \\`setup: { consoleUrl, steps: [...] }\\` to ${where}: where the app is ` +\n        'created, and the steps in order. Write {callbackUrl} and {scopes} where ' +\n        'Ekanos should fill in the exact redirect URI and scopes.',\n    }));\n}\n"]}
+{"version":3,"file":"validate-findings.js","sourceRoot":"","sources":["../src/validate-findings.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  DefinitionCollisionInput,\n  Finding,\n} from '@ekanos/integration-schema';\nimport {\n  collectCollisionFindings,\n  collectDefinitionFindings,\n} from '@ekanos/integration-schema';\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport { collectDesignFindings } from './design-findings';\nimport { preconditionError } from './errors';\nimport { collectIconFindings } from './icon-findings';\nimport { loadDefinition } from './load-definition';\nimport type { LoadedProject } from './project';\nimport {\n  collectDocsFindings,\n  collectHostCompilerRulesFindings,\n  collectLintToolingFindings,\n  collectProjectFindings,\n} from './project-checks';\n\n/**\n * The full findings pass shared by `validate` (which reports them) and\n * `publish` (which refuses to submit on any error-severity finding). One\n * implementation so the publish gate can never drift from what `validate`\n * checks — a project that validates clean is, by construction, a project that\n * publish will accept locally.\n *\n * NOTE on schema skew: an earlier version of this function rewrote the\n * unrecognized-key hint when the project's `@ekanos/integration-schema` was\n * newer than the CLI's (see `schema-skew.ts`). That rewrite was dead code —\n * `assertSchemaNotSkewed` throws PRECONDITION_FAILED before either `validate`\n * or `publish` ever calls this function in that state, so a project-newer\n * finding can never reach here to be rewritten, and the precondition error\n * already names both versions and points at the fix. It was removed rather\n * than kept \"just in case\": if a future caller ever makes validate proceed\n * under skew instead of failing fast, THAT is when a rewrite here becomes\n * necessary again, and it should be reintroduced with a real caller driving\n * it, not tests that fake their own reachability.\n */\nexport async function collectAllFindings(\n  loaded: LoadedProject,\n): Promise<Finding[]> {\n  const findings: Finding[] = [];\n  const definitions: DefinitionCollisionInput[] = [];\n\n  for (const integration of loaded.integrations) {\n    const result = await loadDefinition(\n      integration.entryPath,\n      loaded.projectDir,\n    );\n\n    if (result.ok) {\n      findings.push(\n        ...collectDefinitionFindings(result.definition, {\n          file: integration.entryPath,\n        }),\n      );\n      findings.push(\n        ...collectSlugAgreementFindings(\n          integration,\n          result.definition as { slug?: unknown },\n        ),\n      );\n      findings.push(\n        ...collectVersionAgreementFindings(\n          integration,\n          result.definition as { version?: unknown },\n          loaded.projectDir,\n        ),\n      );\n      findings.push(\n        ...collectOAuthSetupFindings(integration, result.definition),\n      );\n      definitions.push(result.definition as DefinitionCollisionInput);\n      continue;\n    }\n\n    if (result.kind === 'rejected') {\n      // The module loaded but the SDK/schema rejected the definition at import\n      // time — surface it as a validation finding rather than a crash.\n      findings.push({\n        check: 'definition.load',\n        severity: 'error',\n        file: integration.entryPath,\n        message: result.message,\n        hint:\n          'Fix the integration definition so defineIntegration() accepts it, ' +\n          'then re-run validate.',\n      });\n      continue;\n    }\n\n    // A genuine module-load failure is a precondition, not a finding.\n    throw preconditionError(\n      `Could not load the integration definition for \"${integration.slug}\": ` +\n        result.message,\n      'Ensure the entry module and its installed dependencies load under ' +\n        'Node, then re-run validate.',\n    );\n  }\n\n  // Cross-checks only mean something with more than one definition in hand.\n  findings.push(...collectCollisionFindings(definitions));\n  findings.push(...collectProjectFindings(loaded.projectDir));\n  findings.push(...collectLintToolingFindings(loaded.projectDir));\n  findings.push(...collectDocsFindings(loaded.project, loaded.projectDir));\n  findings.push(...collectIconFindings(loaded.projectDir));\n  findings.push(...collectDesignFindings(loaded.projectDir));\n  findings.push(...collectHostCompilerRulesFindings(loaded.projectDir));\n\n  return findings;\n}\n\n/**\n * `ekanos.json` and the definition each carry a slug, and nothing compared\n * them: a project could declare `something-else` while the definition said\n * `repo-activity` and validate would report `{ ok: true, findings: [] }`.\n *\n * That is the identifier every surface addresses the integration by — the\n * harness route, the product slug, the widget id prefix, the MCP server — so\n * two sources of truth disagreeing is not a style question. It is an error,\n * not a warning, for the same reason a silent default is worse than a loud\n * one: the failure it causes shows up somewhere else entirely.\n */\nfunction collectSlugAgreementFindings(\n  integration: { slug: string; entry: string; entryPath: string },\n  definition: { slug?: unknown },\n): Finding[] {\n  const declared = definition.slug;\n  if (typeof declared !== 'string' || declared === integration.slug) return [];\n\n  return [\n    {\n      check: 'project.slug-agreement',\n      severity: 'error',\n      file: integration.entryPath,\n      message:\n        `ekanos.json declares slug \"${integration.slug}\" for this entry, but ` +\n        `the definition says \"${declared}\". The slug addresses the ` +\n        'integration everywhere — its harness route, its product record, its ' +\n        'widget ids — so the two must agree.',\n      hint:\n        `Change one to match the other: either set \"slug\": \"${declared}\" in ` +\n        `ekanos.json, or pass slug: '${integration.slug}' to ` +\n        'defineIntegration().',\n    },\n  ];\n}\n\n/**\n * `package.json`'s `version` field and the `version` `defineIntegration()`\n * declares are two more independent sources of truth for the same fact —\n * this project shipped weather@0.1.1 with a package.json bump, but the\n * declaration itself still said 0.1.0. Generated seeds embed the\n * DECLARATION's version in their header, so a stale declaration produces a\n * seed that looks stale even though the package itself moved on.\n *\n * WARN, not error, unlike slug agreement: a mismatched version is a quality\n * signal a partner should fix, not a broken cross-reference that breaks\n * something else at runtime, so it must not block `publish`. And a project\n * with no package.json, or a package.json with no `version` field, has\n * nothing to compare the declaration against — skip rather than warn on\n * absence.\n */\nexport function collectVersionAgreementFindings(\n  integration: { slug: string; entry: string; entryPath: string },\n  definition: { version?: unknown },\n  projectDir: string,\n): Finding[] {\n  const declared = definition.version;\n  if (typeof declared !== 'string') return [];\n\n  const manifestPath = path.join(projectDir, 'package.json');\n  if (!fs.existsSync(manifestPath)) return [];\n\n  let manifest: unknown;\n  try {\n    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));\n  } catch {\n    // Malformed package.json is npm's problem to report, not a validate\n    // finding — nothing here can compare against an unparseable manifest.\n    return [];\n  }\n\n  const packageVersion =\n    typeof manifest === 'object' && manifest !== null\n      ? (manifest as { version?: unknown }).version\n      : undefined;\n  if (typeof packageVersion !== 'string' || packageVersion === declared) {\n    return [];\n  }\n\n  return [\n    {\n      check: 'project.version-agreement',\n      severity: 'warn',\n      file: integration.entryPath,\n      message:\n        `package.json declares version \"${packageVersion}\", but the ` +\n        `defineIntegration() declaration for \"${integration.slug}\" still ` +\n        `says \"${declared}\". Generated seed headers embed the ` +\n        \"declaration's version, so a stale declaration ships stale-looking \" +\n        'metadata even though the package itself moved on.',\n      hint:\n        `Update the \"version\" passed to defineIntegration() in ` +\n        `${integration.entryPath} to match package.json's \"${packageVersion}\".`,\n    },\n  ];\n}\n\n/**\n * An OAuth connection with no `setup` steps leaves whoever creates its app —\n * the Source admin (`ekanos apps`) or each team — to work out the provider's\n * console alone. A warning, not an error: the connection works without it.\n */\nexport function collectOAuthSetupFindings(\n  integration: { entryPath: string },\n  definition: unknown,\n): Finding[] {\n  if (typeof definition !== 'object' || definition === null) return [];\n  const { oauth, oauthConnections } = definition as {\n    oauth?: { setup?: unknown; teamApp?: unknown };\n    oauthConnections?: Record<string, { setup?: unknown; teamApp?: unknown }>;\n  };\n\n  type Connection = { setup?: unknown; teamApp?: unknown };\n  const connections: Array<readonly [string, Connection]> = [\n    ...(oauth ? [['oauth', oauth] as const] : []),\n    ...Object.entries(oauthConnections ?? {}).map(\n      ([id, connection]) => [`oauthConnections.${id}`, connection] as const,\n    ),\n  ];\n\n  return connections\n    .filter(([, connection]) => connection.setup === undefined)\n    .map(([where, connection]) => ({\n      check: 'oauth.setup-missing',\n      severity: 'warn' as const,\n      file: integration.entryPath,\n      message:\n        `${where} has no setup steps, so ` +\n        (connection.teamApp\n          ? 'each team creating its app'\n          : \"the Source admin creating the Source's app (ekanos apps set)\") +\n        \" gets no guidance in the provider's console.\",\n      hint:\n        `Add \\`setup: { consoleUrl, steps: [...] }\\` to ${where}: where the app is ` +\n        'created, and the steps in order. Write {callbackUrl} and {scopes} where ' +\n        'Ekanos should fill in the exact redirect URI and scopes.',\n    }));\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekanos/cli",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "private": false,
   "description": "The Ekanos partner toolchain CLI: scaffold, validate, and test an Ekanos integration against the published @ekanos packages. Agent-native — every verb speaks JSON with a stable exit-code taxonomy.",
   "keywords": [
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@clack/prompts": "1.7.0",
-    "@ekanos/integration-schema": "0.18.0",
+    "@ekanos/integration-schema": "0.19.0",
     "esbuild": "0.28.1",
     "picocolors": "1.1.1"
   },

package/templates/ekanos.json.tmpl

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

package/templates/experience/AGENTS.md.tmpl

@@ -0,0 +1,22 @@
+# __DISPLAY_NAME__ (an Ekanos experience)
+
+This project is an EXPERIENCE: widgets, pages and workflow templates that depend
+on integrations and reach them only through their pinned contracts. It is not an
+integration itself.
+
+- The integrations it depends on are declared in `ekanos.json` "integrations"
+  (`name` = the integration, `version`, the `operations` it may call) and pinned in
+  `ekanos.lock.json` + `contracts/`. Add one:
+  `ekanos add <integration>@<version> --from-dir <dir>`.
+  Never edit `src/.ekanos/integrations.d.ts`; `ekanos codegen` writes it.
+- Read: `useOperation(integration, 'tool/<name>', input)`. Write:
+  `useOperationMutation(integration, 'action/<name>')` (a person approves each write).
+  Server: `operation(integration, op, input)` from `@ekanos/sdk/experience/server`.
+- Never import integration code (`@companydotcom/integration-*`, a path into an
+  integration repo, `@kit/*`). `ekanos check` and `ekanos build` fail on it.
+- Build UI with `@ekanos/sdk/components` (`Widget.*`) and `@ekanos/ui`, semantic
+  tokens only.
+- To try an unpublished integration, create `ekanos.local.json` (gitignored)
+  with an "integrations" entry pointing at the integration's folder. While any override is active `ekanos publish`
+  refuses.
+- Loop: `ekanos check` then `ekanos build`.

package/templates/experience/ekanos.json.tmpl

@@ -0,0 +1,7 @@
+{
+  "kind": "experience",
+  "slug": "__SLUG__",
+  "entry": "src/experience.ts",
+  "contractsDir": "contracts",
+  "integrations": []
+}

package/templates/experience/ekanos.lock.json.tmpl

@@ -0,0 +1,4 @@
+{
+  "lockfileVersion": 1,
+  "integrations": {}
+}

package/templates/experience/eslint.config.mjs.tmpl

@@ -0,0 +1,25 @@
+/**
+ * Lint config for __SLUG__.
+ *
+ * `@ekanos/sdk/eslint/experience` keeps integration code out of this project:
+ * no `@companydotcom/integration-*`, no path into an integration, no `@kit/*`,
+ * no computed `import()`. An experience XX * integrations (`useOperation`, `operation`, `step.tool`). `ekanos check` re-verifies
+ * the same rule against the real import graph and the built bundle.
+ */
+import experiencePreset from '@ekanos/sdk/eslint/experience';
+import tsParser from '@typescript-eslint/parser';
+
+export default [
+  { ignores: ['dist/**', 'node_modules/**', '.ekanos/**', 'legacy/**'] },
+  {
+    name: '__SLUG__/parser',
+    files: ['src/**/*.ts', 'src/**/*.tsx'],
+    languageOptions: {
+      parser: tsParser,
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      parserOptions: { ecmaFeatures: { jsx: true } },
+    },
+  },
+  ...experiencePreset,
+];

package/templates/experience/gitignore.tmpl

@@ -0,0 +1,17 @@
+# Dependencies
+node_modules/
+
+# Build output (regenerated by `ekanos build`)
+dist/
+manifest.json
+*.tsbuildinfo
+
+# Per-developer: integration overrides and the generated dev harness (root only:
+# src/.ekanos/integrations.d.ts is codegen output and IS committed). Never commit these;
+# `ekanos check` fails if ekanos.local.json is tracked and `ekanos publish`
+# refuses while an override is active.
+ekanos.local.json
+/.ekanos/
+
+# Logs
+*.log

package/templates/experience/package.json.tmpl

@@ -0,0 +1,41 @@
+{
+  "name": "__SLUG__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "An Ekanos experience built with @ekanos/sdk.",
+  "files": [
+    "dist",
+    "manifest.json",
+    "ekanos.json",
+    "ekanos.lock.json",
+    "contracts"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "check": "npx ekanos check",
+    "build": "npx ekanos build"
+  },
+  "dependencies": {
+    "@ekanos/sdk": "^0.19.0",
+    "@ekanos/ui": "^0.19.0",
+    "@tanstack/react-query": "^5.101.4",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@ekanos/cli": "^0.17.0",
+    "@ekanos/harness": "^0.19.0",
+    "@tailwindcss/postcss": "^4.3.3",
+    "@typescript-eslint/parser": "^8.46.2",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "eslint": "^10.11.0",
+    "next": "^16.0.0",
+    "react-hook-form": "^7.68.0",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^5.9.3"
+  }
+}

package/templates/experience/src/.ekanos/integrations.d.ts.tmpl

@@ -0,0 +1,3 @@
+// GENERATED by `ekanos codegen` from the pinned contracts. Do not edit; commit it.
+// Run `ekanos add <integration>@<version>` or `ekanos sync` to change the integrations.
+export {};

package/templates/experience/src/experience.ts.tmpl

@@ -0,0 +1,30 @@
+/**
+ * Your experience, declared in one object.
+ *
+ * The integrations this experience depends on live in ekanos.json "integrations",
+ * not here. Add one with:
+ *
+ *   ekanos add <integration>@<version> --from-dir <contracts folder>
+ *
+ * That pins the integration's contract and generates src/.ekanos/integrations.d.ts,
+ * after which `useOperation('<integration>', 'tool/<name>')` is typed end to end.
+ */
+import { defineExperience } from '@ekanos/sdk/experience';
+
+import { HelloWidget } from './widgets/hello-widget';
+
+export default defineExperience({
+  slug: '__SLUG__',
+  name: '__DISPLAY_NAME__',
+  description: 'A starter experience. Replace this with what it does.',
+  sidebar: { section: '__SLUG__', icon: 'sparkles', label: '__DISPLAY_NAME__' },
+  widgets: [
+    {
+      id: 'hello',
+      title: 'Hello',
+      integrations: [],
+      width: 'half',
+      component: HelloWidget,
+    },
+  ],
+});

package/templates/experience/src/widgets/hello-widget.tsx.tmpl

@@ -0,0 +1,40 @@
+import { Widget } from '@ekanos/sdk/components';
+import {
+  Stat,
+  StatDetail,
+  StatFigure,
+  StatLabel,
+  StatValue,
+} from '@ekanos/ui/stat';
+
+// A starter widget, built like an integration widget: the Widget.* compound
+// API plus the kit's Stat, semantic tokens only, never an inline style.
+//
+// Once you have added an integration, read from it with a typed hook:
+//
+//   import { useOperation } from '@ekanos/sdk/experience/client';
+//   const posts = useOperation('sanity', 'tool/list_posts', { limit: 10 });
+//
+// and write with useOperationMutation, which asks a person to approve first.
+export function HelloWidget() {
+  return (
+    <Widget.DataState>
+      <Widget.Card>
+        <Widget.Header context="Since you scaffolded this" />
+        <Widget.Active>
+          <Widget.Body>
+            <Stat>
+              <StatLabel>Integrations</StatLabel>
+              <StatFigure>
+                <StatValue>0</StatValue>
+              </StatFigure>
+              <StatDetail>Run "ekanos add" to add an integration</StatDetail>
+            </Stat>
+          </Widget.Body>
+        </Widget.Active>
+        <Widget.Loading variant="stat" />
+        <Widget.Error />
+      </Widget.Card>
+    </Widget.DataState>
+  );
+}

package/templates/experience/tsconfig.json.tmpl

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

package/templates/harness/app/%5F%5Fekanos/api/[...path]/route.ts.tmpl

@@ -0,0 +1,9 @@
+import { createEkanosApiHandlers } from '@ekanos/harness/api';
+
+// Next treats a leading underscore folder as private, so this directory is
+// literally named `%5F%5Fekanos` and serves /__ekanos/api/*.
+const handlers = createEkanosApiHandlers();
+
+export const GET = handlers.GET;
+export const POST = handlers.POST;
+export const PUT = handlers.PUT;

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

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

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

@@ -1 +1 @@
-export { IntegrationIndexPage as default } from '@ekanos/harness/routes';
+export { LegacyPreviewRedirect as default } from '@ekanos/harness/routes';

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,17 @@
+'use client';
+
+import { ConsoleLayout } from '@ekanos/harness/routes';
+
+import experience from __EXPERIENCE_ENTRY__;
+
+export default function ExperienceLayout(props: { children: React.ReactNode }) {
+  return (
+    <ConsoleLayout
+      experience={{
+        widgets: experience.widgets ?? [],
+        pages: experience.pages ?? [],
+      }}
+      {...props}
+    />
+  );
+}

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

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

package/templates/harness/app/experience/pages/[id]/page.tsx.tmpl

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

package/templates/harness/app/experience/review-queue/page.tsx.tmpl

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

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

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

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

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

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

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

package/templates/harness/app/experience/workflows/[id]/page.tsx.tmpl

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

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

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

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

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

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

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

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

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

package/templates/harness/app/integrations/[slug]/operations/[kind]/[name]/page.tsx.tmpl

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,5 @@
+import { redirect } from 'next/navigation';
+
+export default function HarnessIndex() {
+  redirect('/experience');
+}

package/templates/harness/repo/app/%5F%5Fekanos/api/[...path]/route.ts.tmpl

@@ -0,0 +1,11 @@
+import { createRepoApiHandlers } from '@ekanos/harness/api';
+
+// Next treats a leading underscore folder as private, so this directory is
+// literally named `%5F%5Fekanos` and serves /__ekanos/api/*. At a repo root it
+// answers the repo overview and forwards `packages/<kind>/<name>/…` to that
+// package's own harness API.
+const handlers = createRepoApiHandlers();
+
+export const GET = handlers.GET;
+export const POST = handlers.POST;
+export const PUT = handlers.PUT;

package/templates/harness/repo/app/(repo)/connections/page.tsx.tmpl

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

package/templates/harness/repo/app/(repo)/layout.tsx.tmpl

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

package/templates/harness/repo/app/(repo)/page.tsx.tmpl

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

package/templates/harness/repo/app/experiences/[name]/connect/page.tsx.tmpl

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

package/templates/harness/repo/app/experiences/[name]/layout.tsx.tmpl

@@ -0,0 +1,9 @@
+'use client';
+
+import { RepoExperienceLayout } from '@ekanos/harness/routes';
+
+import { experienceEntries } from '../../repo-experiences';
+
+export default function ExperienceLayout(props: { children: React.ReactNode }) {
+  return <RepoExperienceLayout entries={experienceEntries} {...props} />;
+}

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

@@ -0,0 +1,5 @@
+import { redirect } from 'next/navigation';
+
+export default function ExperiencesIndex() {
+  redirect('/');
+}

package/templates/harness/repo/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} repo {...props} />;
+}

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

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

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

@@ -0,0 +1,5 @@
+import { redirect } from 'next/navigation';
+
+export default function IntegrationsIndex() {
+  redirect('/');
+}

package/templates/harness/repo/app/repo-experiences.ts.tmpl

@@ -0,0 +1,5 @@
+// Generated by `ekanos dev` at a repo root. One entry per experience package:
+// the widgets and pages are React components only the package's own module holds.
+__EXPERIENCE_IMPORTS__
+export const experienceEntries = {
+__EXPERIENCE_ENTRIES__} as const;

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

@@ -6,7 +6,21 @@
  * `@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';
+/*
+ * `source(none)` turns OFF Tailwind v4's automatic source detection. Left on,
+ * it scans everything under this directory — including `.next/`, whose
+ * Turbopack cache holds binary `.sst` blocks that contain fragments of our
+ * own sources split by control bytes. Those become garbage candidates such as
+ * `var(--icon-glyph<ctrl>,16px)`, and the CSS parser then fails with "Parsing
+ * CSS source code failed": every page a build-error overlay and every
+ * harness API route an HTML 500, recurring whenever the cache is rewritten.
+ * Every directory worth scanning is named by an exact `@source` below or
+ * inside the harness stylesheet.
+ */
+@import '@ekanos/harness/styles.css' source(none);
+
+/* The generated shell's own pages — explicit, so `.next/` is never matched. */
+@source '../app/**/*.tsx';
 
 /*
  * Your integration source, and the registry that lists it. A missing @source

package/templates/package.json.tmpl

@@ -12,12 +12,12 @@
     "prepare": "node scripts/setup-hooks.mjs"
   },
   "dependencies": {
-    "@ekanos/sdk": "^0.18.0",
-    "@ekanos/ui": "^0.18.0"
+    "@ekanos/sdk": "^0.19.0",
+    "@ekanos/ui": "^0.19.0"
   },
   "devDependencies": {
-    "@ekanos/cli": "^0.16.0",
-    "@ekanos/harness": "^0.18.0",
+    "@ekanos/cli": "^0.17.0",
+    "@ekanos/harness": "^0.19.0",
     "@hookform/resolvers": "^5.2.2",
     "@tailwindcss/postcss": "^4.3.3",
     "@tanstack/react-query": "^5.101.4",