@ekanos/cli 0.7.0 → 0.8.0

package/dist/commands/apps.d.ts

@@ -1,3 +1,4 @@
+import type { ProviderAppStatus } from '@ekanos/integration-schema';
 import type { CliContext } from '../context.js';
 import type { ExitCode } from '../exit-codes.js';
 export declare const APPS_SUBCOMMANDS: readonly ['show', 'set'];
@@ -23,3 +24,8 @@ export interface AppsArgs {
  * secret.
  */
 export declare function runApps(ctx: CliContext, args: AppsArgs): Promise<ExitCode>;
+/**
+ * How to create the app: the integration's own steps (`oauth.setup`, with the
+ * callback URL filled in) when it declares them, else the generic three.
+ */
+export declare function walkthrough(status: ProviderAppStatus): string[];

package/dist/commands/apps.js

@@ -29,12 +29,7 @@ export async function runApps(ctx, args) {
     if (subcommand === 'show') {
         return ctx.succeed(Object.assign({ host: env.host }, status), summary(ctx, status));
     }
-    ctx.log([
-        `${status.product.name} app for ${status.source.slug}`,
-        `  1. In ${status.product.name}, create an OAuth app (or open the one you use).`,
-        `  2. Register this callback URL exactly: ${status.callbackUrl}`,
-        `  3. Enter its client ID and secret below. The secret is stored in Ekanos's vault and never shown again.`,
-    ].join('\n'));
+    ctx.log(walkthrough(status).join('\n'));
     if (status.configured) {
         const replace = await ((_a = args.confirm) !== null && _a !== void 0 ? _a : promptYesNo)(`${status.source.slug} already has ${status.product.name} credentials. Replace them? [y/N]`);
         if (!replace) {
@@ -63,9 +58,48 @@ export async function runApps(ctx, args) {
         ],
     }));
 }
+/**
+ * How to create the app: the integration's own steps (`oauth.setup`, with the
+ * callback URL filled in) when it declares them, else the generic three.
+ */
+export function walkthrough(status) {
+    var _a, _b, _c;
+    const name = status.product.name;
+    const lines = [`${name} app for ${status.source.slug}`];
+    if ((_a = status.setup) === null || _a === void 0 ? void 0 : _a.consoleUrl) {
+        lines.push(`  Open: ${status.setup.consoleUrl}`);
+    }
+    const steps = ((_b = status.setup) === null || _b === void 0 ? void 0 : _b.steps.length)
+        ? [
+            ...status.setup.steps,
+            `Make sure the callback URL is exactly: ${status.callbackUrl}`,
+        ]
+        : [
+            `In ${name}, create an OAuth app (or open the one you use).`,
+            `Register this callback URL exactly: ${status.callbackUrl}`,
+        ];
+    steps.push("Enter its client ID and secret below. The secret is stored in Ekanos's vault and never shown again.");
+    lines.push(...steps.map((step, index) => `  ${index + 1}. ${step}`));
+    if ((_c = status.setup) === null || _c === void 0 ? void 0 : _c.guideUrl)
+        lines.push(`  Guide: ${status.setup.guideUrl}`);
+    return lines;
+}
 function summary(ctx, status) {
     const rows = [
         ['Source', status.source.slug],
+        ...(status.setup
+            ? [
+                [
+                    'How to create it',
+                    [
+                        ...(status.setup.consoleUrl
+                            ? [`Open ${status.setup.consoleUrl}`]
+                            : []),
+                        ...status.setup.steps.map((step, index) => `${index + 1}. ${step}`),
+                    ],
+                ],
+            ]
+            : []),
         [
             'Set up',
             status.configured

package/dist/commands/apps.js.map

@@ -1 +1 @@
-{"version":3,"file":"apps.js","sourceRoot":"","sources":["../../src/commands/apps.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ProviderAppStatus } from '@ekanos/integration-schema';\n\nimport {\n  type AppsApiResult,\n  setProviderApp,\n  showProviderApp,\n} from '../apps-api';\nimport type { StoredSession } from '../auth/credential-store';\nimport {\n  type AuthEnvironment,\n  refreshStoredSession,\n  requireSession,\n  resolveAuthEnvironment,\n} from '../auth/session';\nimport type { CliContext } from '../context';\nimport { authRequiredError, usageError, validationError } from '../errors';\nimport type { ExitCode } from '../exit-codes';\nimport { resolveSourceTarget } from '../source-target';\nimport type { ResultRow } from '../ui';\nimport { promptYesNo } from './publish';\n\nexport const APPS_SUBCOMMANDS = ['show', 'set'] as const;\ntype AppsSubcommand = (typeof APPS_SUBCOMMANDS)[number];\n\nexport interface AppsArgs {\n  host?: string;\n  source?: string;\n  subcommand?: string;\n  product?: string;\n  dir: string;\n  env: Record<string, string | undefined>;\n  stdinIsTTY?: boolean;\n  /** Test seams for the questions `set` asks. */\n  ask?: (question: string) => Promise<string>;\n  askSecret?: (question: string) => Promise<string>;\n  confirm?: (question: string) => Promise<boolean>;\n}\n\n/**\n * `apps` — a Source's provider apps: the OAuth client an integration signs\n * every team in through (Linear's, say). `show` says whether the Source has\n * one and which callback URL to register; `set` takes the client id and\n * secret from the Source admin at the terminal — never from a flag, a file\n * or a non-interactive run, so an agent driving the CLI never handles the\n * secret.\n */\nexport async function runApps(\n  ctx: CliContext,\n  args: AppsArgs,\n): Promise<ExitCode> {\n  const subcommand = parseSubcommand(args.subcommand);\n  const product = requireProduct(args.product, subcommand);\n\n  if (subcommand === 'set' && !canPrompt(ctx, args)) {\n    throw usageError(\n      'apps set takes the client secret at a terminal, never in a script or an agent run.',\n      `Run it yourself in your terminal: npx @ekanos/cli apps set ${product}${args.source ? ` --source ${args.source}` : ''}`,\n    );\n  }\n\n  const env = resolveAuthEnvironment(ctx, args.host, args.env, {\n    projectDir: args.dir,\n  });\n  const resolved = await resolveSourceTarget(\n    env,\n    requireSession(env.store, env.host),\n    args,\n  );\n  const client = new AppsClient(env, resolved.session);\n  const source = resolved.source;\n\n  const status = await client.call((token) =>\n    showProviderApp(env.host, token, source, product),\n  );\n\n  if (subcommand === 'show') {\n    return ctx.succeed({ host: env.host, ...status }, summary(ctx, status));\n  }\n\n  ctx.log(\n    [\n      `${status.product.name} app for ${status.source.slug}`,\n      `  1. In ${status.product.name}, create an OAuth app (or open the one you use).`,\n      `  2. Register this callback URL exactly: ${status.callbackUrl}`,\n      `  3. Enter its client ID and secret below. The secret is stored in Ekanos's vault and never shown again.`,\n    ].join('\\n'),\n  );\n  if (status.configured) {\n    const replace = await (args.confirm ?? promptYesNo)(\n      `${status.source.slug} already has ${status.product.name} credentials. Replace them? [y/N]`,\n    );\n    if (!replace) {\n      throw validationError(\n        'Nothing was changed.',\n        `Run \"ekanos apps show ${product}\" to see the current state.`,\n      );\n    }\n  }\n\n  const clientId = (await (args.ask ?? promptLine)('Client ID: ')).trim();\n  const clientSecret = (\n    await (args.askSecret ?? promptHidden)('Client secret (hidden): ')\n  ).trim();\n  if (!clientId || !clientSecret) {\n    throw validationError(\n      'Both the client ID and the client secret are needed.',\n      `Run \"ekanos apps set ${product}\" again.`,\n    );\n  }\n\n  const result = await client.call((token) =>\n    setProviderApp(env.host, token, {\n      source,\n      product,\n      clientId,\n      clientSecret,\n    }),\n  );\n  return ctx.succeed(\n    { host: env.host, ...result },\n    ctx.ui.result({\n      title: result.replaced\n        ? `Replaced the ${result.product.name} app`\n        : `Set up the ${result.product.name} app`,\n      rows: [\n        ['Source', result.source.slug],\n        ['Teams can connect', result.configured ? 'yes' : 'not yet'],\n        ['Callback URL', result.callbackUrl],\n      ],\n    }),\n  );\n}\n\nfunction summary(ctx: CliContext, status: ProviderAppStatus): string {\n  const rows: ResultRow[] = [\n    ['Source', status.source.slug],\n    [\n      'Set up',\n      status.configured\n        ? 'yes — teams can connect'\n        : 'no — no team can connect yet',\n    ],\n    ['Callback URL', status.callbackUrl],\n  ];\n  return [\n    ctx.ui.result({ title: `${status.product.name} app`, rows }),\n    ...(status.configured\n      ? []\n      : [\n          ctx.ui.hint(\n            `Run \"ekanos apps set ${status.product.slug}\" in your terminal to enter its credentials.`,\n          ),\n        ]),\n  ].join('\\n');\n}\n\nclass AppsClient {\n  constructor(\n    private readonly env: AuthEnvironment,\n    private session: StoredSession,\n  ) {}\n\n  async call<T>(\n    send: (accessToken: string) => Promise<AppsApiResult<T>>,\n  ): Promise<T> {\n    let result = await send(this.session.accessToken);\n    if (result.status === 'unauthorized') {\n      this.session = await refreshStoredSession(this.env, this.session);\n      result = await send(this.session.accessToken);\n    }\n    if (result.status === 'ok') return result.data;\n    throw authRequiredError(\n      `The session for ${this.env.host} could not authorize the apps call.`,\n      `Run \"ekanos login --host ${this.env.host}\" and retry.`,\n    );\n  }\n}\n\nfunction canPrompt(ctx: CliContext, args: AppsArgs): boolean {\n  return !ctx.jsonMode && (args.stdinIsTTY ?? process.stdin.isTTY === true);\n}\n\nfunction parseSubcommand(value: string | undefined): AppsSubcommand {\n  const match = APPS_SUBCOMMANDS.find((name) => name === value);\n  if (match) return match;\n  throw usageError(\n    value ? `Unknown apps subcommand \"${value}\".` : 'apps needs a subcommand.',\n    `Run one of: ${APPS_SUBCOMMANDS.map((name) => `ekanos apps ${name} <product>`).join(', ')}.`,\n  );\n}\n\nfunction requireProduct(value: string | undefined, verb: string): string {\n  const slug = value?.trim().toLowerCase();\n  if (slug && /^[a-z0-9][a-z0-9-]*$/.test(slug)) return slug;\n  throw usageError(\n    value\n      ? `\"${value}\" is not a product slug.`\n      : `apps ${verb} needs a product.`,\n    `Pass the product's slug, e.g. \"ekanos apps ${verb} linear\". \"ekanos catalog\" lists them.`,\n  );\n}\n\nasync function promptLine(question: string): Promise<string> {\n  const readline = await import('node:readline/promises');\n  const rl = readline.createInterface({\n    input: process.stdin,\n    output: process.stderr,\n  });\n  try {\n    return await rl.question(question);\n  } finally {\n    rl.close();\n  }\n}\n\n/** Read a line without echoing it: the secret never appears on screen or in scrollback. */\nasync function promptHidden(question: string): Promise<string> {\n  const readline = await import('node:readline');\n  process.stderr.write(question);\n  const rl = readline.createInterface({\n    input: process.stdin,\n    output: process.stderr,\n    terminal: true,\n  });\n  // Swallow readline's echo of each keystroke; the question is already written.\n  (rl as unknown as { _writeToOutput: (text: string) => void })._writeToOutput =\n    () => {};\n  try {\n    return await new Promise<string>((resolve) => {\n      rl.question('', resolve);\n    });\n  } finally {\n    rl.close();\n    process.stderr.write('\\n');\n  }\n}\n"]}
+{"version":3,"file":"apps.js","sourceRoot":"","sources":["../../src/commands/apps.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ProviderAppStatus } from '@ekanos/integration-schema';\n\nimport {\n  type AppsApiResult,\n  setProviderApp,\n  showProviderApp,\n} from '../apps-api';\nimport type { StoredSession } from '../auth/credential-store';\nimport {\n  type AuthEnvironment,\n  refreshStoredSession,\n  requireSession,\n  resolveAuthEnvironment,\n} from '../auth/session';\nimport type { CliContext } from '../context';\nimport { authRequiredError, usageError, validationError } from '../errors';\nimport type { ExitCode } from '../exit-codes';\nimport { resolveSourceTarget } from '../source-target';\nimport type { ResultRow } from '../ui';\nimport { promptYesNo } from './publish';\n\nexport const APPS_SUBCOMMANDS = ['show', 'set'] as const;\ntype AppsSubcommand = (typeof APPS_SUBCOMMANDS)[number];\n\nexport interface AppsArgs {\n  host?: string;\n  source?: string;\n  subcommand?: string;\n  product?: string;\n  dir: string;\n  env: Record<string, string | undefined>;\n  stdinIsTTY?: boolean;\n  /** Test seams for the questions `set` asks. */\n  ask?: (question: string) => Promise<string>;\n  askSecret?: (question: string) => Promise<string>;\n  confirm?: (question: string) => Promise<boolean>;\n}\n\n/**\n * `apps` — a Source's provider apps: the OAuth client an integration signs\n * every team in through (Linear's, say). `show` says whether the Source has\n * one and which callback URL to register; `set` takes the client id and\n * secret from the Source admin at the terminal — never from a flag, a file\n * or a non-interactive run, so an agent driving the CLI never handles the\n * secret.\n */\nexport async function runApps(\n  ctx: CliContext,\n  args: AppsArgs,\n): Promise<ExitCode> {\n  const subcommand = parseSubcommand(args.subcommand);\n  const product = requireProduct(args.product, subcommand);\n\n  if (subcommand === 'set' && !canPrompt(ctx, args)) {\n    throw usageError(\n      'apps set takes the client secret at a terminal, never in a script or an agent run.',\n      `Run it yourself in your terminal: npx @ekanos/cli apps set ${product}${args.source ? ` --source ${args.source}` : ''}`,\n    );\n  }\n\n  const env = resolveAuthEnvironment(ctx, args.host, args.env, {\n    projectDir: args.dir,\n  });\n  const resolved = await resolveSourceTarget(\n    env,\n    requireSession(env.store, env.host),\n    args,\n  );\n  const client = new AppsClient(env, resolved.session);\n  const source = resolved.source;\n\n  const status = await client.call((token) =>\n    showProviderApp(env.host, token, source, product),\n  );\n\n  if (subcommand === 'show') {\n    return ctx.succeed({ host: env.host, ...status }, summary(ctx, status));\n  }\n\n  ctx.log(walkthrough(status).join('\\n'));\n  if (status.configured) {\n    const replace = await (args.confirm ?? promptYesNo)(\n      `${status.source.slug} already has ${status.product.name} credentials. Replace them? [y/N]`,\n    );\n    if (!replace) {\n      throw validationError(\n        'Nothing was changed.',\n        `Run \"ekanos apps show ${product}\" to see the current state.`,\n      );\n    }\n  }\n\n  const clientId = (await (args.ask ?? promptLine)('Client ID: ')).trim();\n  const clientSecret = (\n    await (args.askSecret ?? promptHidden)('Client secret (hidden): ')\n  ).trim();\n  if (!clientId || !clientSecret) {\n    throw validationError(\n      'Both the client ID and the client secret are needed.',\n      `Run \"ekanos apps set ${product}\" again.`,\n    );\n  }\n\n  const result = await client.call((token) =>\n    setProviderApp(env.host, token, {\n      source,\n      product,\n      clientId,\n      clientSecret,\n    }),\n  );\n  return ctx.succeed(\n    { host: env.host, ...result },\n    ctx.ui.result({\n      title: result.replaced\n        ? `Replaced the ${result.product.name} app`\n        : `Set up the ${result.product.name} app`,\n      rows: [\n        ['Source', result.source.slug],\n        ['Teams can connect', result.configured ? 'yes' : 'not yet'],\n        ['Callback URL', result.callbackUrl],\n      ],\n    }),\n  );\n}\n\n/**\n * How to create the app: the integration's own steps (`oauth.setup`, with the\n * callback URL filled in) when it declares them, else the generic three.\n */\nexport function walkthrough(status: ProviderAppStatus): string[] {\n  const name = status.product.name;\n  const lines = [`${name} app for ${status.source.slug}`];\n  if (status.setup?.consoleUrl) {\n    lines.push(`  Open: ${status.setup.consoleUrl}`);\n  }\n  const steps = status.setup?.steps.length\n    ? [\n        ...status.setup.steps,\n        `Make sure the callback URL is exactly: ${status.callbackUrl}`,\n      ]\n    : [\n        `In ${name}, create an OAuth app (or open the one you use).`,\n        `Register this callback URL exactly: ${status.callbackUrl}`,\n      ];\n  steps.push(\n    \"Enter its client ID and secret below. The secret is stored in Ekanos's vault and never shown again.\",\n  );\n  lines.push(...steps.map((step, index) => `  ${index + 1}. ${step}`));\n  if (status.setup?.guideUrl) lines.push(`  Guide: ${status.setup.guideUrl}`);\n  return lines;\n}\n\nfunction summary(ctx: CliContext, status: ProviderAppStatus): string {\n  const rows: ResultRow[] = [\n    ['Source', status.source.slug],\n    ...(status.setup\n      ? ([\n          [\n            'How to create it',\n            [\n              ...(status.setup.consoleUrl\n                ? [`Open ${status.setup.consoleUrl}`]\n                : []),\n              ...status.setup.steps.map(\n                (step, index) => `${index + 1}. ${step}`,\n              ),\n            ],\n          ],\n        ] as const)\n      : []),\n    [\n      'Set up',\n      status.configured\n        ? 'yes — teams can connect'\n        : 'no — no team can connect yet',\n    ],\n    ['Callback URL', status.callbackUrl],\n  ];\n  return [\n    ctx.ui.result({ title: `${status.product.name} app`, rows }),\n    ...(status.configured\n      ? []\n      : [\n          ctx.ui.hint(\n            `Run \"ekanos apps set ${status.product.slug}\" in your terminal to enter its credentials.`,\n          ),\n        ]),\n  ].join('\\n');\n}\n\nclass AppsClient {\n  constructor(\n    private readonly env: AuthEnvironment,\n    private session: StoredSession,\n  ) {}\n\n  async call<T>(\n    send: (accessToken: string) => Promise<AppsApiResult<T>>,\n  ): Promise<T> {\n    let result = await send(this.session.accessToken);\n    if (result.status === 'unauthorized') {\n      this.session = await refreshStoredSession(this.env, this.session);\n      result = await send(this.session.accessToken);\n    }\n    if (result.status === 'ok') return result.data;\n    throw authRequiredError(\n      `The session for ${this.env.host} could not authorize the apps call.`,\n      `Run \"ekanos login --host ${this.env.host}\" and retry.`,\n    );\n  }\n}\n\nfunction canPrompt(ctx: CliContext, args: AppsArgs): boolean {\n  return !ctx.jsonMode && (args.stdinIsTTY ?? process.stdin.isTTY === true);\n}\n\nfunction parseSubcommand(value: string | undefined): AppsSubcommand {\n  const match = APPS_SUBCOMMANDS.find((name) => name === value);\n  if (match) return match;\n  throw usageError(\n    value ? `Unknown apps subcommand \"${value}\".` : 'apps needs a subcommand.',\n    `Run one of: ${APPS_SUBCOMMANDS.map((name) => `ekanos apps ${name} <product>`).join(', ')}.`,\n  );\n}\n\nfunction requireProduct(value: string | undefined, verb: string): string {\n  const slug = value?.trim().toLowerCase();\n  if (slug && /^[a-z0-9][a-z0-9-]*$/.test(slug)) return slug;\n  throw usageError(\n    value\n      ? `\"${value}\" is not a product slug.`\n      : `apps ${verb} needs a product.`,\n    `Pass the product's slug, e.g. \"ekanos apps ${verb} linear\". \"ekanos catalog\" lists them.`,\n  );\n}\n\nasync function promptLine(question: string): Promise<string> {\n  const readline = await import('node:readline/promises');\n  const rl = readline.createInterface({\n    input: process.stdin,\n    output: process.stderr,\n  });\n  try {\n    return await rl.question(question);\n  } finally {\n    rl.close();\n  }\n}\n\n/** Read a line without echoing it: the secret never appears on screen or in scrollback. */\nasync function promptHidden(question: string): Promise<string> {\n  const readline = await import('node:readline');\n  process.stderr.write(question);\n  const rl = readline.createInterface({\n    input: process.stdin,\n    output: process.stderr,\n    terminal: true,\n  });\n  // Swallow readline's echo of each keystroke; the question is already written.\n  (rl as unknown as { _writeToOutput: (text: string) => void })._writeToOutput =\n    () => {};\n  try {\n    return await new Promise<string>((resolve) => {\n      rl.question('', resolve);\n    });\n  } finally {\n    rl.close();\n    process.stderr.write('\\n');\n  }\n}\n"]}

package/dist/commands/catalog.js

@@ -96,8 +96,12 @@ function productDetail(ui, product) {
     }
     rows.push([
         'Setup',
-        product.setupSteps.map((step, index) => `${index + 1}. [${step.state}] ${step.title} (${step.actor}) — ${step.detail}` +
-            (step.guideUrl ? ` ${step.guideUrl}` : '')),
+        product.setupSteps.flatMap((step, index) => { var _a; return [
+            `${index + 1}. [${step.state}] ${step.title} (${step.actor}) — ${step.detail}` +
+                (step.guideUrl ? ` ${step.guideUrl}` : ''),
+            ...(step.consoleUrl ? [`   Open ${step.consoleUrl}`] : []),
+            ...((_a = step.instructions) !== null && _a !== void 0 ? _a : []).map((line, lineIndex) => `   ${String.fromCharCode(97 + lineIndex)}. ${line}`),
+        ]; }),
     ]);
     return ui.result({ title: `${product.name} (${product.slug})`, rows });
 }

package/dist/commands/catalog.js.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../src/commands/catalog.ts"],"names":[],"mappings":"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","sourcesContent":["import type { CatalogProduct, SourceCatalog } from '@ekanos/integration-schema';\n\nimport {\n  refreshStoredSession,\n  requireSession,\n  resolveAuthEnvironment,\n} from '../auth/session';\nimport {\n  type FetchSourceCatalogResult,\n  fetchSourceCatalog,\n} from '../catalog-api';\nimport type { CliContext } from '../context';\nimport { authRequiredError } from '../errors';\nimport type { ExitCode } from '../exit-codes';\nimport { resolveSourceTarget } from '../source-target';\nimport { type Ui, pluralize } from '../ui';\nimport { withDocsHint } from './agents-init';\n\nexport interface CatalogArgs {\n  host?: string;\n  source?: string;\n  /** One product's detail, when given. */\n  product?: string;\n  dir: string;\n  env: Record<string, string | undefined>;\n}\n\n/**\n * `catalog` — what the Source can already do (plan 239.0). Lists every\n * product the Source can use, with its tools, agent events and the steps\n * left to set it up; `ekanos catalog <product>` shows one in full.\n *\n * Read before building: an agent migration asks it first, so a capability\n * the Source already has is set up rather than rebuilt. Works outside a\n * project — the Source comes from `--source`, else `ekanos.json`, else the\n * caller's only seat.\n */\nexport async function runCatalog(\n  ctx: CliContext,\n  args: CatalogArgs,\n): Promise<ExitCode> {\n  const env = resolveAuthEnvironment(ctx, args.host, args.env, {\n    projectDir: args.dir,\n  });\n  let session = requireSession(env.store, env.host);\n\n  const resolved = await resolveSourceTarget(env, session, args);\n  session = resolved.session;\n\n  const query = { source: resolved.source, product: args.product };\n  let result = await fetchSourceCatalog(env.host, session.accessToken, query);\n  if (result.status === 'unauthorized') {\n    session = await refreshStoredSession(env, session);\n    result = await fetchSourceCatalog(env.host, session.accessToken, query);\n  }\n  const catalog = requireCatalog(result, env.host);\n\n  return ctx.succeed(\n    { host: env.host, ...catalog },\n    withDocsHint(\n      ctx.ui,\n      args.dir,\n      args.product\n        ? productDetail(ctx.ui, catalog.products[0]!)\n        : catalogSummary(ctx.ui, catalog),\n    ),\n  );\n}\n\nfunction requireCatalog(\n  result: FetchSourceCatalogResult,\n  host: string,\n): SourceCatalog {\n  if (result.status === 'ok') return result.catalog;\n  throw authRequiredError(\n    `The session for ${host} could not authorize the catalog read.`,\n    `Run \"ekanos login --host ${host}\" and retry.`,\n  );\n}\n\nconst AVAILABILITY_LABEL = {\n  enabled: 'Enabled on this Source',\n  'turned-off': 'Granted but switched off',\n  available: 'Available — ask Ekanos to enable',\n} as const;\n\nfunction catalogSummary(ui: Ui, catalog: SourceCatalog): string {\n  const blocks = (['enabled', 'turned-off', 'available'] as const)\n    .map((availability) => {\n      const products = catalog.products.filter(\n        (product) => product.availability === availability,\n      );\n      if (products.length === 0) return null;\n      return ui.result({\n        title: `${AVAILABILITY_LABEL[availability]} (${products.length})`,\n        tone: availability === 'enabled' ? 'ok' : 'warn',\n        rows: products.map((product): [string, string] => [\n          product.slug,\n          [product.name, describeShape(product), openSteps(product)]\n            .filter(Boolean)\n            .join(' · '),\n        ]),\n      });\n    })\n    .filter((block): block is string => block !== null);\n\n  return [\n    ...blocks,\n    ui.hint(\n      `${pluralize(catalog.products.length, 'product')} on ${catalog.source.slug}. ` +\n        `\"ekanos catalog <product>\" shows tools, agent events and setup steps.`,\n    ),\n  ].join('\\n\\n');\n}\n\nfunction productDetail(ui: Ui, product: CatalogProduct): string {\n  const rows: [string, string | string[]][] = [\n    ['What', product.summary ?? '—'],\n    [\n      'Kind',\n      product.kind === 'experience' ? 'Ekanos Experience' : 'Integration',\n    ],\n    ['Status', AVAILABILITY_LABEL[product.availability]],\n  ];\n  if (product.connectedTeams !== null) {\n    rows.push(['Teams connected', String(product.connectedTeams)]);\n  }\n  if (product.tools.length > 0) {\n    rows.push([\n      'Tools',\n      product.tools.map(\n        (tool) =>\n          `${tool.name} (${tool.effect}${tool.sensitivity === 'undeclared' ? '' : `, ${tool.sensitivity}`})`,\n      ),\n    ]);\n  }\n  if (product.agentEvents.length > 0) {\n    rows.push([\n      'Agent triggers',\n      product.agentEvents.map((event) => `${event.id} — ${event.label}`),\n    ]);\n  }\n  if (product.agentReplyTool) {\n    rows.push(['Replies with', product.agentReplyTool]);\n  }\n  rows.push([\n    'Setup',\n    product.setupSteps.map(\n      (step, index) =>\n        `${index + 1}. [${step.state}] ${step.title} (${step.actor}) — ${step.detail}` +\n        (step.guideUrl ? ` ${step.guideUrl}` : ''),\n    ),\n  ]);\n\n  return ui.result({ title: `${product.name} (${product.slug})`, rows });\n}\n\nfunction describeShape(product: CatalogProduct): string {\n  const parts = [\n    product.tools.length > 0 ? pluralize(product.tools.length, 'tool') : null,\n    product.agentEvents.length > 0\n      ? pluralize(product.agentEvents.length, 'agent trigger')\n      : null,\n  ].filter(Boolean);\n  return parts.join(', ');\n}\n\nfunction openSteps(product: CatalogProduct): string {\n  const open = product.setupSteps.filter((step) => step.state === 'todo');\n  return open.length === 0 ? '' : `${pluralize(open.length, 'step')} left`;\n}\n"]}
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../src/commands/catalog.ts"],"names":[],"mappings":"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","sourcesContent":["import type { CatalogProduct, SourceCatalog } from '@ekanos/integration-schema';\n\nimport {\n  refreshStoredSession,\n  requireSession,\n  resolveAuthEnvironment,\n} from '../auth/session';\nimport {\n  type FetchSourceCatalogResult,\n  fetchSourceCatalog,\n} from '../catalog-api';\nimport type { CliContext } from '../context';\nimport { authRequiredError } from '../errors';\nimport type { ExitCode } from '../exit-codes';\nimport { resolveSourceTarget } from '../source-target';\nimport { type Ui, pluralize } from '../ui';\nimport { withDocsHint } from './agents-init';\n\nexport interface CatalogArgs {\n  host?: string;\n  source?: string;\n  /** One product's detail, when given. */\n  product?: string;\n  dir: string;\n  env: Record<string, string | undefined>;\n}\n\n/**\n * `catalog` — what the Source can already do (plan 239.0). Lists every\n * product the Source can use, with its tools, agent events and the steps\n * left to set it up; `ekanos catalog <product>` shows one in full.\n *\n * Read before building: an agent migration asks it first, so a capability\n * the Source already has is set up rather than rebuilt. Works outside a\n * project — the Source comes from `--source`, else `ekanos.json`, else the\n * caller's only seat.\n */\nexport async function runCatalog(\n  ctx: CliContext,\n  args: CatalogArgs,\n): Promise<ExitCode> {\n  const env = resolveAuthEnvironment(ctx, args.host, args.env, {\n    projectDir: args.dir,\n  });\n  let session = requireSession(env.store, env.host);\n\n  const resolved = await resolveSourceTarget(env, session, args);\n  session = resolved.session;\n\n  const query = { source: resolved.source, product: args.product };\n  let result = await fetchSourceCatalog(env.host, session.accessToken, query);\n  if (result.status === 'unauthorized') {\n    session = await refreshStoredSession(env, session);\n    result = await fetchSourceCatalog(env.host, session.accessToken, query);\n  }\n  const catalog = requireCatalog(result, env.host);\n\n  return ctx.succeed(\n    { host: env.host, ...catalog },\n    withDocsHint(\n      ctx.ui,\n      args.dir,\n      args.product\n        ? productDetail(ctx.ui, catalog.products[0]!)\n        : catalogSummary(ctx.ui, catalog),\n    ),\n  );\n}\n\nfunction requireCatalog(\n  result: FetchSourceCatalogResult,\n  host: string,\n): SourceCatalog {\n  if (result.status === 'ok') return result.catalog;\n  throw authRequiredError(\n    `The session for ${host} could not authorize the catalog read.`,\n    `Run \"ekanos login --host ${host}\" and retry.`,\n  );\n}\n\nconst AVAILABILITY_LABEL = {\n  enabled: 'Enabled on this Source',\n  'turned-off': 'Granted but switched off',\n  available: 'Available — ask Ekanos to enable',\n} as const;\n\nfunction catalogSummary(ui: Ui, catalog: SourceCatalog): string {\n  const blocks = (['enabled', 'turned-off', 'available'] as const)\n    .map((availability) => {\n      const products = catalog.products.filter(\n        (product) => product.availability === availability,\n      );\n      if (products.length === 0) return null;\n      return ui.result({\n        title: `${AVAILABILITY_LABEL[availability]} (${products.length})`,\n        tone: availability === 'enabled' ? 'ok' : 'warn',\n        rows: products.map((product): [string, string] => [\n          product.slug,\n          [product.name, describeShape(product), openSteps(product)]\n            .filter(Boolean)\n            .join(' · '),\n        ]),\n      });\n    })\n    .filter((block): block is string => block !== null);\n\n  return [\n    ...blocks,\n    ui.hint(\n      `${pluralize(catalog.products.length, 'product')} on ${catalog.source.slug}. ` +\n        `\"ekanos catalog <product>\" shows tools, agent events and setup steps.`,\n    ),\n  ].join('\\n\\n');\n}\n\nfunction productDetail(ui: Ui, product: CatalogProduct): string {\n  const rows: [string, string | string[]][] = [\n    ['What', product.summary ?? '—'],\n    [\n      'Kind',\n      product.kind === 'experience' ? 'Ekanos Experience' : 'Integration',\n    ],\n    ['Status', AVAILABILITY_LABEL[product.availability]],\n  ];\n  if (product.connectedTeams !== null) {\n    rows.push(['Teams connected', String(product.connectedTeams)]);\n  }\n  if (product.tools.length > 0) {\n    rows.push([\n      'Tools',\n      product.tools.map(\n        (tool) =>\n          `${tool.name} (${tool.effect}${tool.sensitivity === 'undeclared' ? '' : `, ${tool.sensitivity}`})`,\n      ),\n    ]);\n  }\n  if (product.agentEvents.length > 0) {\n    rows.push([\n      'Agent triggers',\n      product.agentEvents.map((event) => `${event.id} — ${event.label}`),\n    ]);\n  }\n  if (product.agentReplyTool) {\n    rows.push(['Replies with', product.agentReplyTool]);\n  }\n  rows.push([\n    'Setup',\n    product.setupSteps.flatMap((step, index) => [\n      `${index + 1}. [${step.state}] ${step.title} (${step.actor}) — ${step.detail}` +\n        (step.guideUrl ? ` ${step.guideUrl}` : ''),\n      ...(step.consoleUrl ? [`   Open ${step.consoleUrl}`] : []),\n      ...(step.instructions ?? []).map(\n        (line, lineIndex) =>\n          `   ${String.fromCharCode(97 + lineIndex)}. ${line}`,\n      ),\n    ]),\n  ]);\n\n  return ui.result({ title: `${product.name} (${product.slug})`, rows });\n}\n\nfunction describeShape(product: CatalogProduct): string {\n  const parts = [\n    product.tools.length > 0 ? pluralize(product.tools.length, 'tool') : null,\n    product.agentEvents.length > 0\n      ? pluralize(product.agentEvents.length, 'agent trigger')\n      : null,\n  ].filter(Boolean);\n  return parts.join(', ');\n}\n\nfunction openSteps(product: CatalogProduct): string {\n  const open = product.setupSteps.filter((step) => step.state === 'todo');\n  return open.length === 0 ? '' : `${pluralize(open.length, 'step')} left`;\n}\n"]}

package/dist/validate-findings.d.ts

@@ -42,3 +42,11 @@ export declare function collectVersionAgreementFindings(integration: {
 }, definition: {
     version?: unknown;
 }, projectDir: string): Finding[];
+/**
+ * An OAuth connection with no `setup` steps leaves whoever creates its app —
+ * the Source admin (`ekanos apps`) or each team — to work out the provider's
+ * console alone. A warning, not an error: the connection works without it.
+ */
+export declare function collectOAuthSetupFindings(integration: {
+    entryPath: string;
+}, definition: unknown): Finding[];

package/dist/validate-findings.js

@@ -36,6 +36,7 @@ export async function collectAllFindings(loaded) {
             }));
             findings.push(...collectSlugAgreementFindings(integration, result.definition));
             findings.push(...collectVersionAgreementFindings(integration, result.definition, loaded.projectDir));
+            findings.push(...collectOAuthSetupFindings(integration, result.definition));
             definitions.push(result.definition);
             continue;
         }
@@ -148,4 +149,33 @@ export function collectVersionAgreementFindings(integration, definition, project
         },
     ];
 }
+/**
+ * An OAuth connection with no `setup` steps leaves whoever creates its app —
+ * the Source admin (`ekanos apps`) or each team — to work out the provider's
+ * console alone. A warning, not an error: the connection works without it.
+ */
+export function collectOAuthSetupFindings(integration, definition) {
+    if (typeof definition !== 'object' || definition === null)
+        return [];
+    const { oauth, oauthConnections } = definition;
+    const connections = [
+        ...(oauth ? [['oauth', oauth]] : []),
+        ...Object.entries(oauthConnections !== null && oauthConnections !== void 0 ? oauthConnections : {}).map(([id, connection]) => [`oauthConnections.${id}`, connection]),
+    ];
+    return connections
+        .filter(([, connection]) => connection.setup === undefined)
+        .map(([where, connection]) => ({
+        check: 'oauth.setup-missing',
+        severity: 'warn',
+        file: integration.entryPath,
+        message: `${where} has no setup steps, so ` +
+            (connection.teamApp
+                ? 'each team creating its app'
+                : "the Source admin creating the Source's app (ekanos apps set)") +
+            " gets no guidance in the provider's console.",
+        hint: `Add \`setup: { consoleUrl, steps: [...] }\` to ${where}: where the app is ` +
+            'created, and the steps in order. Write {callbackUrl} and {scopes} where ' +
+            'Ekanos should fill in the exact redirect URI and scopes.',
+    }));
+}
 //# sourceMappingURL=validate-findings.js.map

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      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"]}
+{"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"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekanos/cli",
-  "version": "0.7.0",
+  "version": "0.8.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.10.0",
+    "@ekanos/integration-schema": "0.11.0",
     "esbuild": "0.28.1",
     "picocolors": "1.1.1"
   },

package/templates/package.json.tmpl

@@ -12,12 +12,12 @@
     "prepare": "node scripts/setup-hooks.mjs"
   },
   "dependencies": {
-    "@ekanos/sdk": "^0.10.0",
-    "@ekanos/ui": "^0.10.0"
+    "@ekanos/sdk": "^0.11.0",
+    "@ekanos/ui": "^0.11.0"
   },
   "devDependencies": {
-    "@ekanos/cli": "^0.7.0",
-    "@ekanos/harness": "^0.7.1",
+    "@ekanos/cli": "^0.8.0",
+    "@ekanos/harness": "^0.7.2",
     "@hookform/resolvers": "^5.2.2",
     "@tailwindcss/postcss": "^4.3.3",
     "@tanstack/react-query": "^5.101.4",

package/templates/skills/build-integration/references/oauth-setup.md

@@ -41,6 +41,26 @@ the default is HTTP Basic (`'client_secret_basic'`), but a provider that wants
 harness derives the rest — provider host, redirect URI, scopes, PKCE — from
 `defineIntegration({ oauth })`, so do not repeat those in `notes`.
 
+Also declare the same guidance **on the connection itself** for the hosted
+product — `setup` in `defineIntegration({ oauth: { … } })` (and on each
+`oauthConnections` entry). That is what a Source admin sees in `ekanos apps`
+and a team sees in its setup panel once the integration is live:
+
+```ts
+setup: {
+  consoleUrl: 'https://<provider developer console>/apps/new',
+  steps: [
+    'Create an app and set its callback URL to {callbackUrl}.',
+    'Enable the scopes {scopes}.',
+    'Copy <the console's name for the client id> and <for the secret>.',
+  ],
+},
+```
+
+Ekanos fills `{callbackUrl}` and `{scopes}`; write the console's own words
+for everything else. `ekanos validate` warns (`oauth.setup-missing`) about
+a connection without it.
+
 ## What the harness then shows (so you can point the user at it)
 
 The Activation surface (`npx ekanos dev` → `http://localhost:3100/<slug>/activation`)