@ekanos/cli 0.17.1 → 0.19.0

package/dist/toolchain-api.d.ts

@@ -23,6 +23,11 @@ import { type ToolchainNote, type ToolchainVersions } from './toolchain.js';
  *                                                                  // host
  *                                                                  // refuses
  *         notes?:   [{ level: "warn" | "info", message: string }],
+ *         capabilities?: { experienceSubmissions?: boolean },   // optional
+ *                                                  // host features; a host
+ *                                                  // that predates one omits
+ *                                                  // the key and a caller
+ *                                                  // reads that as "no"
  *       } }
  *     → any other status, or a body that fails to parse or match this shape
  *
@@ -46,10 +51,20 @@ import { type ToolchainNote, type ToolchainVersions } from './toolchain.js';
  * outright rather than quietly papered over by the npm fallback.
  * ---------------------------------------------------------------------------
  */
+/**
+ * Optional host features, advertised additively. A key the host does not send
+ * reads as `false`, so an older deployment behaves exactly as before.
+ */
+export interface HostCapabilities {
+    /** `POST /api/partner/submissions` accepts `kind=experience` and the host admits it. */
+    experienceSubmissions: boolean;
+}
 export interface ToolchainReport {
     current: ToolchainVersions;
     minimum: ToolchainVersions;
     notes: ToolchainNote[];
+    /** Absent when the host sent none (an older host). */
+    capabilities?: HostCapabilities;
 }
 export type FetchToolchainResult = {
     status: 'ok';

package/dist/toolchain-api.js

@@ -48,7 +48,18 @@ function parseReport(body) {
     }
     const rawNotes = data.notes;
     const notes = Array.isArray(rawNotes) ? rawNotes.filter(isNote) : [];
-    return { current, minimum, notes };
+    const capabilities = parseCapabilities(data.capabilities);
+    return Object.assign({ current,
+        minimum,
+        notes }, (capabilities ? { capabilities } : {}));
+}
+function parseCapabilities(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    return {
+        experienceSubmissions: value.experienceSubmissions ===
+            true,
+    };
 }
 function parseVersions(value) {
     if (typeof value !== 'object' || value === null)

package/dist/toolchain-api.js.map

@@ -1 +1 @@
-{"version":3,"file":"toolchain-api.js","sourceRoot":"","sources":["../src/toolchain-api.ts"],"names":[],"mappings":"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","sourcesContent":["import { request } from './auth/ekanos-api';\nimport {\n  TOOLCHAIN_PACKAGES,\n  type ToolchainNote,\n  type ToolchainVersions,\n  firstInexactVersion,\n} from './toolchain';\n\n/**\n * The CLI's client for the Ekanos toolchain-advisory route.\n *\n * ---------------------------------------------------------------------------\n * WIRE CONTRACT — the seam between this package and the Ekanos web app.\n *\n * The server side is the host's `/api/partner/toolchain` route and ships on\n * a DIFFERENT BRANCH from this file, same as every other route in\n * `auth/ekanos-api.ts` and `publish-api.ts`. Nothing here imports host code;\n * the two halves are coupled only by HTTP, and the tests stub `fetch`,\n * never the route.\n *\n *   GET /api/partner/toolchain   [Authorization: Bearer <access_token>]\n *     → 200 { ok: true, data: {\n *         current:  { cli, sdk, ui, integrationSchema, harness },  // the\n *                                                                  // coherent\n *                                                                  // set the\n *                                                                  // host\n *                                                                  // recommends\n *         minimum:  { cli, sdk, ui, integrationSchema, harness },  // below\n *                                                                  // this the\n *                                                                  // host\n *                                                                  // refuses\n *         notes?:   [{ level: \"warn\" | \"info\", message: string }],\n *       } }\n *     → any other status, or a body that fails to parse or match this shape\n *\n * This endpoint is treated as ADVISORY, not authoritative in the way the auth\n * and submission routes are: a 404 (an older Ekanos deployment that predates\n * this route) or a 501 (deliberately unimplemented) are both entirely\n * ordinary, and a 4xx/5xx/network failure/malformed body all mean exactly the\n * same thing to every caller — \"the endpoint is unavailable, fall back to the\n * npm registry\" — so this module never throws. There is no not-configured\n * distinction to make here the way `cli-config` has: a caller with no way to\n * reach this route at all (no host, no session) never calls it in the first\n * place; see `toolchain-resolve.ts`.\n *\n * Unknown extra fields in the response are tolerated (only the fields above\n * are read); a missing `notes` defaults to an empty array.\n *\n * The one exception to \"never throws, always falls back\": a version that is\n * present but is not an exact semver (`1.2.3`, `1.2.3-rc.1`) is `invalid`, not\n * `unavailable`. Each version becomes a `pnpm add -E` spec, so a value like\n * `github:owner/repo` is a host trying to install code; that is refused\n * outright rather than quietly papered over by the npm fallback.\n * ---------------------------------------------------------------------------\n */\n\nexport interface ToolchainReport {\n  current: ToolchainVersions;\n  minimum: ToolchainVersions;\n  notes: ToolchainNote[];\n}\n\nexport type FetchToolchainResult =\n  | { status: 'ok'; report: ToolchainReport }\n  | { status: 'invalid'; detail: string }\n  | { status: 'unavailable' };\n\nexport async function fetchToolchainReport(\n  host: string,\n  accessToken: string,\n): Promise<FetchToolchainResult> {\n  try {\n    const response = await request(`${host}/api/partner/toolchain`, {\n      method: 'GET',\n      headers: {\n        accept: 'application/json',\n        authorization: `Bearer ${accessToken}`,\n      },\n    });\n\n    if (!response.ok) return { status: 'unavailable' };\n\n    const body: unknown = await response.json();\n    const report = parseReport(body);\n\n    if (report === null) return { status: 'unavailable' };\n    if ('invalid' in report)\n      return { status: 'invalid', detail: report.invalid };\n    return { status: 'ok', report };\n  } catch {\n    // Network failure, timeout, or a body that is not even JSON — all read\n    // the same: the endpoint is unavailable this time, fall back to npm.\n    return { status: 'unavailable' };\n  }\n}\n\nfunction parseReport(\n  body: unknown,\n): ToolchainReport | { invalid: string } | null {\n  if (typeof body !== 'object' || body === null) return null;\n  const data = (body as { data?: unknown }).data;\n  if (typeof data !== 'object' || data === null) return null;\n\n  const current = parseVersions((data as { current?: unknown }).current);\n  const minimum = parseVersions((data as { minimum?: unknown }).minimum);\n  if (!current || !minimum) return null;\n\n  for (const [label, versions] of [\n    ['current', current],\n    ['minimum', minimum],\n  ] as const) {\n    const bad = firstInexactVersion(versions);\n    if (bad) {\n      return {\n        invalid: `the host's ${label} ${TOOLCHAIN_PACKAGES[bad.key]} is ${JSON.stringify(bad.value)}, which is not an exact version`,\n      };\n    }\n  }\n\n  const rawNotes = (data as { notes?: unknown }).notes;\n  const notes = Array.isArray(rawNotes) ? rawNotes.filter(isNote) : [];\n\n  return { current, minimum, notes };\n}\n\nfunction parseVersions(value: unknown): ToolchainVersions | null {\n  if (typeof value !== 'object' || value === null) return null;\n  const record = value as Record<string, unknown>;\n  const result: Partial<ToolchainVersions> = {};\n\n  for (const key of Object.keys(\n    TOOLCHAIN_PACKAGES,\n  ) as (keyof ToolchainVersions)[]) {\n    const raw = record[key];\n    if (typeof raw !== 'string' || raw.length === 0) return null;\n    result[key] = raw;\n  }\n\n  return result as ToolchainVersions;\n}\n\nfunction isNote(value: unknown): value is ToolchainNote {\n  if (typeof value !== 'object' || value === null) return false;\n  const note = value as { level?: unknown; message?: unknown };\n  return (\n    (note.level === 'warn' || note.level === 'info') &&\n    typeof note.message === 'string'\n  );\n}\n"]}
+{"version":3,"file":"toolchain-api.js","sourceRoot":"","sources":["../src/toolchain-api.ts"],"names":[],"mappings":"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","sourcesContent":["import { request } from './auth/ekanos-api';\nimport {\n  TOOLCHAIN_PACKAGES,\n  type ToolchainNote,\n  type ToolchainVersions,\n  firstInexactVersion,\n} from './toolchain';\n\n/**\n * The CLI's client for the Ekanos toolchain-advisory route.\n *\n * ---------------------------------------------------------------------------\n * WIRE CONTRACT — the seam between this package and the Ekanos web app.\n *\n * The server side is the host's `/api/partner/toolchain` route and ships on\n * a DIFFERENT BRANCH from this file, same as every other route in\n * `auth/ekanos-api.ts` and `publish-api.ts`. Nothing here imports host code;\n * the two halves are coupled only by HTTP, and the tests stub `fetch`,\n * never the route.\n *\n *   GET /api/partner/toolchain   [Authorization: Bearer <access_token>]\n *     → 200 { ok: true, data: {\n *         current:  { cli, sdk, ui, integrationSchema, harness },  // the\n *                                                                  // coherent\n *                                                                  // set the\n *                                                                  // host\n *                                                                  // recommends\n *         minimum:  { cli, sdk, ui, integrationSchema, harness },  // below\n *                                                                  // this the\n *                                                                  // host\n *                                                                  // refuses\n *         notes?:   [{ level: \"warn\" | \"info\", message: string }],\n *         capabilities?: { experienceSubmissions?: boolean },   // optional\n *                                                  // host features; a host\n *                                                  // that predates one omits\n *                                                  // the key and a caller\n *                                                  // reads that as \"no\"\n *       } }\n *     → any other status, or a body that fails to parse or match this shape\n *\n * This endpoint is treated as ADVISORY, not authoritative in the way the auth\n * and submission routes are: a 404 (an older Ekanos deployment that predates\n * this route) or a 501 (deliberately unimplemented) are both entirely\n * ordinary, and a 4xx/5xx/network failure/malformed body all mean exactly the\n * same thing to every caller — \"the endpoint is unavailable, fall back to the\n * npm registry\" — so this module never throws. There is no not-configured\n * distinction to make here the way `cli-config` has: a caller with no way to\n * reach this route at all (no host, no session) never calls it in the first\n * place; see `toolchain-resolve.ts`.\n *\n * Unknown extra fields in the response are tolerated (only the fields above\n * are read); a missing `notes` defaults to an empty array.\n *\n * The one exception to \"never throws, always falls back\": a version that is\n * present but is not an exact semver (`1.2.3`, `1.2.3-rc.1`) is `invalid`, not\n * `unavailable`. Each version becomes a `pnpm add -E` spec, so a value like\n * `github:owner/repo` is a host trying to install code; that is refused\n * outright rather than quietly papered over by the npm fallback.\n * ---------------------------------------------------------------------------\n */\n\n/**\n * Optional host features, advertised additively. A key the host does not send\n * reads as `false`, so an older deployment behaves exactly as before.\n */\nexport interface HostCapabilities {\n  /** `POST /api/partner/submissions` accepts `kind=experience` and the host admits it. */\n  experienceSubmissions: boolean;\n}\n\nexport interface ToolchainReport {\n  current: ToolchainVersions;\n  minimum: ToolchainVersions;\n  notes: ToolchainNote[];\n  /** Absent when the host sent none (an older host). */\n  capabilities?: HostCapabilities;\n}\n\nexport type FetchToolchainResult =\n  | { status: 'ok'; report: ToolchainReport }\n  | { status: 'invalid'; detail: string }\n  | { status: 'unavailable' };\n\nexport async function fetchToolchainReport(\n  host: string,\n  accessToken: string,\n): Promise<FetchToolchainResult> {\n  try {\n    const response = await request(`${host}/api/partner/toolchain`, {\n      method: 'GET',\n      headers: {\n        accept: 'application/json',\n        authorization: `Bearer ${accessToken}`,\n      },\n    });\n\n    if (!response.ok) return { status: 'unavailable' };\n\n    const body: unknown = await response.json();\n    const report = parseReport(body);\n\n    if (report === null) return { status: 'unavailable' };\n    if ('invalid' in report)\n      return { status: 'invalid', detail: report.invalid };\n    return { status: 'ok', report };\n  } catch {\n    // Network failure, timeout, or a body that is not even JSON — all read\n    // the same: the endpoint is unavailable this time, fall back to npm.\n    return { status: 'unavailable' };\n  }\n}\n\nfunction parseReport(\n  body: unknown,\n): ToolchainReport | { invalid: string } | null {\n  if (typeof body !== 'object' || body === null) return null;\n  const data = (body as { data?: unknown }).data;\n  if (typeof data !== 'object' || data === null) return null;\n\n  const current = parseVersions((data as { current?: unknown }).current);\n  const minimum = parseVersions((data as { minimum?: unknown }).minimum);\n  if (!current || !minimum) return null;\n\n  for (const [label, versions] of [\n    ['current', current],\n    ['minimum', minimum],\n  ] as const) {\n    const bad = firstInexactVersion(versions);\n    if (bad) {\n      return {\n        invalid: `the host's ${label} ${TOOLCHAIN_PACKAGES[bad.key]} is ${JSON.stringify(bad.value)}, which is not an exact version`,\n      };\n    }\n  }\n\n  const rawNotes = (data as { notes?: unknown }).notes;\n  const notes = Array.isArray(rawNotes) ? rawNotes.filter(isNote) : [];\n\n  const capabilities = parseCapabilities(\n    (data as { capabilities?: unknown }).capabilities,\n  );\n\n  return {\n    current,\n    minimum,\n    notes,\n    ...(capabilities ? { capabilities } : {}),\n  };\n}\n\nfunction parseCapabilities(value: unknown): HostCapabilities | null {\n  if (typeof value !== 'object' || value === null) return null;\n\n  return {\n    experienceSubmissions:\n      (value as { experienceSubmissions?: unknown }).experienceSubmissions ===\n      true,\n  };\n}\n\nfunction parseVersions(value: unknown): ToolchainVersions | null {\n  if (typeof value !== 'object' || value === null) return null;\n  const record = value as Record<string, unknown>;\n  const result: Partial<ToolchainVersions> = {};\n\n  for (const key of Object.keys(\n    TOOLCHAIN_PACKAGES,\n  ) as (keyof ToolchainVersions)[]) {\n    const raw = record[key];\n    if (typeof raw !== 'string' || raw.length === 0) return null;\n    result[key] = raw;\n  }\n\n  return result as ToolchainVersions;\n}\n\nfunction isNote(value: unknown): value is ToolchainNote {\n  if (typeof value !== 'object' || value === null) return false;\n  const note = value as { level?: unknown; message?: unknown };\n  return (\n    (note.level === 'warn' || note.level === 'info') &&\n    typeof note.message === 'string'\n  );\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekanos/cli",
-  "version": "0.17.1",
+  "version": "0.19.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.19.0",
+    "@ekanos/integration-schema": "0.21.0",
     "esbuild": "0.28.1",
     "picocolors": "1.1.1"
   },

package/templates/experience/package.json.tmpl

@@ -5,6 +5,9 @@
   "type": "module",
   "description": "An Ekanos experience built with @ekanos/sdk.",
   "files": [
+    "src",
+    "tsconfig.json",
+    "npm-shrinkwrap.json",
     "dist",
     "manifest.json",
     "ekanos.json",
@@ -18,16 +21,16 @@
     "build": "npx ekanos build"
   },
   "dependencies": {
-    "@ekanos/sdk": "^0.19.0",
-    "@ekanos/ui": "^0.19.0",
+    "@ekanos/sdk": "^0.21.0",
+    "@ekanos/ui": "^0.21.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",
+    "@ekanos/cli": "^0.19.0",
+    "@ekanos/harness": "^0.21.0",
     "@tailwindcss/postcss": "^4.3.3",
     "@typescript-eslint/parser": "^8.46.2",
     "@types/react": "^19.2.0",

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

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

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

@@ -10,6 +10,9 @@ export default function ExperienceLayout(props: { children: React.ReactNode }) {
       experience={{
         widgets: experience.widgets ?? [],
         pages: experience.pages ?? [],
+        ...(experience.suggestedLayout
+          ? { suggestedLayout: experience.suggestedLayout }
+          : {}),
       }}
       {...props}
     />

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

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

package/templates/package.json.tmpl

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