@ekanos/cli 0.4.2 → 0.5.0

package/README.md

@@ -27,6 +27,8 @@ npx @ekanos/cli dev
 | `whoami`   | Print the identity the stored session authenticates as, plus a compact `seats` list (slug + roles) from the same endpoint `sources` uses — degrades to `seats: null` rather than failing if that lookup is unavailable.                                                                                                                                       |
 | `status`   | The read verb: login state for the resolved host, this project's `ekanos.json`, and its submissions on the host (`GET /api/partner/submissions`). Never fails just because you are logged out — it reports `authenticated: false` instead.                                                                                                                    |
 | `sources`  | List every Ekanos source you hold a developer or source-admin seat on (`GET /api/partner/sources`), with a marker on this project's current publish target.                                                                                                                                                                                                   |
+| `catalog`  | `ekanos catalog [<product-slug>]` — what a source can already use (`GET /api/partner/catalog`): every product enabled, switched off or available to enable, with its tools, agent triggers and generated setup steps. Check it before building something the source may already have.                                                               |
+| `agents`   | `ekanos agents list | show | pull | apply | publish | rollback` — the source's agents, held by Ekanos (`/api/partner/agents`). `apply` stores a new version as a draft, `publish` makes a version the one every team runs, `rollback` publishes an earlier one. Either seat applies; only the source admin publishes.
 | `use`      | `ekanos use <source-slug>` — set this project's publish target to a source you hold a seat on. Refuses (`forbidden`, with your actual seats in the hint) for a slug you don't hold a seat on, so a typo can't silently repoint a project.                                                                                                                     |
 | `publish`  | Validate, pack and submit the integration to an Ekanos host — refusing (`forbidden`) a target you hold no seat on, and confirming an ambiguous multi-seat target before submitting. See [Publish target verification](#publish-target-verification).                                                                                                           |
 | `upgrade`  | Move this toolchain to a coherent target version, with verify-and-rollback. `--check` reports current vs. target and changes nothing; a bare `upgrade` installs, verifies (`validate` + the test script), and rolls back automatically on any failure. See [Keeping the toolchain current](#keeping-the-toolchain-current).                                   |
@@ -419,7 +421,7 @@ ekanos logout
 
 ### Host resolution
 
-`logout`, `whoami`, `status`, `sources`, `use` and `publish` resolve the Ekanos
+`logout`, `whoami`, `status`, `sources`, `catalog`, `agents`, `use` and `publish` resolve the Ekanos
 host in this order:
 
 1. the `--host` flag

package/dist/agents-api.d.ts

@@ -0,0 +1,35 @@
+import { type AgentTemplateApplyRequest, type AgentTemplateList, type AgentTemplateResult, type AgentTemplateShow } from '@ekanos/integration-schema';
+/**
+ * The CLI's client for Source agent templates (plan 239.0 / 239.2).
+ *
+ * ---------------------------------------------------------------------------
+ * WIRE CONTRACT — the `AgentTemplate*` schemas in `@ekanos/integration-schema`,
+ * which the host's `/api/partner/agents` routes build and this parses.
+ *
+ *   GET  /api/partner/agents?source=<slug|id>          → { ok, data: AgentTemplateList }
+ *   GET  /api/partner/agents/<key>?source=<slug|id>    → { ok, data: AgentTemplateShow }
+ *   POST /api/partner/agents            AgentTemplateApplyRequest   → { ok, data: AgentTemplateResult }
+ *   POST /api/partner/agents/<key>/publish   { source, version? }   → { ok, data: AgentTemplateResult }
+ *   POST /api/partner/agents/<key>/rollback  { source, version }    → { ok, data: AgentTemplateResult }
+ *
+ *   → 401 / 3xx                        refresh once and retry
+ *   → 400 { code: "INVALID_AGENT", issues: AgentTemplateIssue[] }
+ *   → 403 { code: "MFA_REQUIRED" | "FORBIDDEN" | "SOURCE_ADMIN_REQUIRED" }
+ *   → 404 { code: "SOURCE_NOT_FOUND" | "TEMPLATE_NOT_FOUND" | "VERSION_NOT_FOUND" }
+ *   → 409 { code: "VERSION_CONFLICT", latestVersion }
+ * ---------------------------------------------------------------------------
+ */
+export type AgentsApiResult<T> = {
+    status: 'ok';
+    data: T;
+} | {
+    status: 'unauthorized';
+};
+export declare function listAgentTemplates(host: string, accessToken: string, source: string): Promise<AgentsApiResult<AgentTemplateList>>;
+export declare function showAgentTemplate(host: string, accessToken: string, source: string, key: string): Promise<AgentsApiResult<AgentTemplateShow>>;
+export declare function applyAgentTemplate(host: string, accessToken: string, body: AgentTemplateApplyRequest): Promise<AgentsApiResult<AgentTemplateResult>>;
+export declare function publishAgentTemplate(host: string, accessToken: string, action: 'publish' | 'rollback', params: {
+    source: string;
+    key: string;
+    version?: number;
+}): Promise<AgentsApiResult<AgentTemplateResult>>;

package/dist/agents-api.js

@@ -0,0 +1,115 @@
+import { AgentTemplateIssueSchema, AgentTemplateListSchema, AgentTemplateResultSchema, AgentTemplateShowSchema, } from '@ekanos/integration-schema';
+import { request } from './auth/ekanos-api.js';
+import { authRequiredError, forbiddenError, invalidStateError, networkError, notFoundError, usageError, validationError, } from './errors.js';
+const ROUTE = '/api/partner/agents';
+export function listAgentTemplates(host, accessToken, source) {
+    return call(host, accessToken, AgentTemplateListSchema, {
+        method: 'GET',
+        path: `${ROUTE}?${new URLSearchParams({ source })}`,
+        subject: source,
+    });
+}
+export function showAgentTemplate(host, accessToken, source, key) {
+    return call(host, accessToken, AgentTemplateShowSchema, {
+        method: 'GET',
+        path: `${ROUTE}/${encodeURIComponent(key)}?${new URLSearchParams({ source })}`,
+        subject: key,
+    });
+}
+export function applyAgentTemplate(host, accessToken, body) {
+    return call(host, accessToken, AgentTemplateResultSchema, {
+        method: 'POST',
+        path: ROUTE,
+        body,
+        subject: body.key,
+    });
+}
+export function publishAgentTemplate(host, accessToken, action, params) {
+    return call(host, accessToken, AgentTemplateResultSchema, {
+        method: 'POST',
+        path: `${ROUTE}/${encodeURIComponent(params.key)}/${action}`,
+        body: { source: params.source, version: params.version },
+        subject: params.key,
+    });
+}
+async function call(host, accessToken, schema, init) {
+    const response = await request(`${host}${init.path}`, {
+        method: init.method,
+        headers: Object.assign({ accept: 'application/json', authorization: `Bearer ${accessToken}` }, (init.body === undefined
+            ? {}
+            : { 'content-type': 'application/json' })),
+        body: init.body === undefined ? undefined : JSON.stringify(init.body),
+    });
+    if (response.status === 401 || isRedirect(response.status)) {
+        return { status: 'unauthorized' };
+    }
+    const body = await readOptionalJson(response);
+    const code = str(body.code);
+    const message = str(body.error);
+    if (response.status === 400 && code === 'INVALID_AGENT') {
+        const issues = readIssues(body.issues);
+        throw validationError([
+            message !== null && message !== void 0 ? message : 'The host refused the agent.',
+            ...issues.map((issue) => `  ${issue.path}: ${issue.message}`),
+        ].join('\n'), `Fix the agent and apply again. "ekanos catalog" lists the products ` +
+            `and tools this Source has.`);
+    }
+    if (response.status === 400) {
+        throw usageError(message !== null && message !== void 0 ? message : 'The host refused the request.', 'See "ekanos agents --help" for each subcommand\'s arguments.');
+    }
+    if (response.status === 403 && code === 'MFA_REQUIRED') {
+        throw authRequiredError(message !== null && message !== void 0 ? message : `${host} requires multi-factor authentication.`, `Complete MFA in the browser, then run "ekanos login" again.`);
+    }
+    if (response.status === 403) {
+        throw forbiddenError(message !== null && message !== void 0 ? message : 'Not permitted on this Source.', code === 'SOURCE_ADMIN_REQUIRED'
+            ? `Only a Source admin publishes. Ask one to run it, or apply as a draft.`
+            : `Run "ekanos sources" to list the sources you hold a seat on.`);
+    }
+    if (response.status === 404) {
+        throw notFoundError(message !== null && message !== void 0 ? message : `"${init.subject}" was not found.`, code === 'SOURCE_NOT_FOUND'
+            ? `Run "ekanos sources" to list the sources you hold a seat on.`
+            : `Run "ekanos agents list" to see this Source's agents and versions.`);
+    }
+    if (response.status === 409 && code === 'VERSION_CONFLICT') {
+        const latest = typeof body.latestVersion === 'number' ? body.latestVersion : null;
+        throw invalidStateError(message !== null && message !== void 0 ? message : `"${init.subject}" changed since you read it` +
+            (latest ? ` (now version ${latest}).` : '.'), `Run "ekanos agents show ${init.subject}" to see the latest, then apply ` +
+            `again — or pass --overwrite to replace it.`);
+    }
+    if (!response.ok) {
+        throw networkError(`${host}${init.path.split('?')[0]} responded ${response.status}.`, response.status >= 500
+            ? `The Ekanos deployment returned a server error. Retry shortly.`
+            : `Confirm the host runs a build that includes the agents routes.`);
+    }
+    const parsed = schema.safeParse(body.data);
+    if (!parsed.success) {
+        throw networkError(`${host}${ROUTE} answered in a shape this CLI does not read.`, `Run "ekanos upgrade" — the CLI and the host disagree on the agents contract.`);
+    }
+    return { status: 'ok', data: parsed.data };
+}
+function readIssues(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((issue) => {
+        const parsed = AgentTemplateIssueSchema.safeParse(issue);
+        return parsed.success ? [parsed.data] : [];
+    });
+}
+async function readOptionalJson(response) {
+    try {
+        const parsed = await response.json();
+        return typeof parsed === 'object' && parsed !== null
+            ? parsed
+            : {};
+    }
+    catch (_a) {
+        return {};
+    }
+}
+function isRedirect(status) {
+    return status >= 300 && status < 400;
+}
+function str(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+//# sourceMappingURL=agents-api.js.map

package/dist/agents-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-api.js","sourceRoot":"","sources":["../src/agents-api.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  type AgentTemplateApplyRequest,\n  type AgentTemplateIssue,\n  AgentTemplateIssueSchema,\n  type AgentTemplateList,\n  AgentTemplateListSchema,\n  type AgentTemplateResult,\n  AgentTemplateResultSchema,\n  type AgentTemplateShow,\n  AgentTemplateShowSchema,\n} from '@ekanos/integration-schema';\nimport type { z } from 'zod';\n\nimport { request } from './auth/ekanos-api';\nimport {\n  authRequiredError,\n  forbiddenError,\n  invalidStateError,\n  networkError,\n  notFoundError,\n  usageError,\n  validationError,\n} from './errors';\n\n/**\n * The CLI's client for Source agent templates (plan 239.0 / 239.2).\n *\n * ---------------------------------------------------------------------------\n * WIRE CONTRACT — the `AgentTemplate*` schemas in `@ekanos/integration-schema`,\n * which the host's `/api/partner/agents` routes build and this parses.\n *\n *   GET  /api/partner/agents?source=<slug|id>          → { ok, data: AgentTemplateList }\n *   GET  /api/partner/agents/<key>?source=<slug|id>    → { ok, data: AgentTemplateShow }\n *   POST /api/partner/agents            AgentTemplateApplyRequest   → { ok, data: AgentTemplateResult }\n *   POST /api/partner/agents/<key>/publish   { source, version? }   → { ok, data: AgentTemplateResult }\n *   POST /api/partner/agents/<key>/rollback  { source, version }    → { ok, data: AgentTemplateResult }\n *\n *   → 401 / 3xx                        refresh once and retry\n *   → 400 { code: \"INVALID_AGENT\", issues: AgentTemplateIssue[] }\n *   → 403 { code: \"MFA_REQUIRED\" | \"FORBIDDEN\" | \"SOURCE_ADMIN_REQUIRED\" }\n *   → 404 { code: \"SOURCE_NOT_FOUND\" | \"TEMPLATE_NOT_FOUND\" | \"VERSION_NOT_FOUND\" }\n *   → 409 { code: \"VERSION_CONFLICT\", latestVersion }\n * ---------------------------------------------------------------------------\n */\n\nexport type AgentsApiResult<T> =\n  | { status: 'ok'; data: T }\n  | { status: 'unauthorized' };\n\nconst ROUTE = '/api/partner/agents';\n\nexport function listAgentTemplates(\n  host: string,\n  accessToken: string,\n  source: string,\n): Promise<AgentsApiResult<AgentTemplateList>> {\n  return call(host, accessToken, AgentTemplateListSchema, {\n    method: 'GET',\n    path: `${ROUTE}?${new URLSearchParams({ source })}`,\n    subject: source,\n  });\n}\n\nexport function showAgentTemplate(\n  host: string,\n  accessToken: string,\n  source: string,\n  key: string,\n): Promise<AgentsApiResult<AgentTemplateShow>> {\n  return call(host, accessToken, AgentTemplateShowSchema, {\n    method: 'GET',\n    path: `${ROUTE}/${encodeURIComponent(key)}?${new URLSearchParams({ source })}`,\n    subject: key,\n  });\n}\n\nexport function applyAgentTemplate(\n  host: string,\n  accessToken: string,\n  body: AgentTemplateApplyRequest,\n): Promise<AgentsApiResult<AgentTemplateResult>> {\n  return call(host, accessToken, AgentTemplateResultSchema, {\n    method: 'POST',\n    path: ROUTE,\n    body,\n    subject: body.key,\n  });\n}\n\nexport function publishAgentTemplate(\n  host: string,\n  accessToken: string,\n  action: 'publish' | 'rollback',\n  params: { source: string; key: string; version?: number },\n): Promise<AgentsApiResult<AgentTemplateResult>> {\n  return call(host, accessToken, AgentTemplateResultSchema, {\n    method: 'POST',\n    path: `${ROUTE}/${encodeURIComponent(params.key)}/${action}`,\n    body: { source: params.source, version: params.version },\n    subject: params.key,\n  });\n}\n\nasync function call<T>(\n  host: string,\n  accessToken: string,\n  schema: z.ZodType<T>,\n  init: {\n    method: 'GET' | 'POST';\n    path: string;\n    body?: unknown;\n    /** What a 404 is about, for the message. */\n    subject: string;\n  },\n): Promise<AgentsApiResult<T>> {\n  const response = await request(`${host}${init.path}`, {\n    method: init.method,\n    headers: {\n      accept: 'application/json',\n      authorization: `Bearer ${accessToken}`,\n      ...(init.body === undefined\n        ? {}\n        : { 'content-type': 'application/json' }),\n    },\n    body: init.body === undefined ? undefined : JSON.stringify(init.body),\n  });\n\n  if (response.status === 401 || isRedirect(response.status)) {\n    return { status: 'unauthorized' };\n  }\n\n  const body = await readOptionalJson(response);\n  const code = str(body.code);\n  const message = str(body.error);\n\n  if (response.status === 400 && code === 'INVALID_AGENT') {\n    const issues = readIssues(body.issues);\n    throw validationError(\n      [\n        message ?? 'The host refused the agent.',\n        ...issues.map((issue) => `  ${issue.path}: ${issue.message}`),\n      ].join('\\n'),\n      `Fix the agent and apply again. \"ekanos catalog\" lists the products ` +\n        `and tools this Source has.`,\n    );\n  }\n\n  if (response.status === 400) {\n    throw usageError(\n      message ?? 'The host refused the request.',\n      'See \"ekanos agents --help\" for each subcommand\\'s arguments.',\n    );\n  }\n\n  if (response.status === 403 && code === 'MFA_REQUIRED') {\n    throw authRequiredError(\n      message ?? `${host} requires multi-factor authentication.`,\n      `Complete MFA in the browser, then run \"ekanos login\" again.`,\n    );\n  }\n\n  if (response.status === 403) {\n    throw forbiddenError(\n      message ?? 'Not permitted on this Source.',\n      code === 'SOURCE_ADMIN_REQUIRED'\n        ? `Only a Source admin publishes. Ask one to run it, or apply as a draft.`\n        : `Run \"ekanos sources\" to list the sources you hold a seat on.`,\n    );\n  }\n\n  if (response.status === 404) {\n    throw notFoundError(\n      message ?? `\"${init.subject}\" was not found.`,\n      code === 'SOURCE_NOT_FOUND'\n        ? `Run \"ekanos sources\" to list the sources you hold a seat on.`\n        : `Run \"ekanos agents list\" to see this Source's agents and versions.`,\n    );\n  }\n\n  if (response.status === 409 && code === 'VERSION_CONFLICT') {\n    const latest =\n      typeof body.latestVersion === 'number' ? body.latestVersion : null;\n    throw invalidStateError(\n      message ??\n        `\"${init.subject}\" changed since you read it` +\n          (latest ? ` (now version ${latest}).` : '.'),\n      `Run \"ekanos agents show ${init.subject}\" to see the latest, then apply ` +\n        `again — or pass --overwrite to replace it.`,\n    );\n  }\n\n  if (!response.ok) {\n    throw networkError(\n      `${host}${init.path.split('?')[0]} responded ${response.status}.`,\n      response.status >= 500\n        ? `The Ekanos deployment returned a server error. Retry shortly.`\n        : `Confirm the host runs a build that includes the agents routes.`,\n    );\n  }\n\n  const parsed = schema.safeParse(body.data);\n  if (!parsed.success) {\n    throw networkError(\n      `${host}${ROUTE} answered in a shape this CLI does not read.`,\n      `Run \"ekanos upgrade\" — the CLI and the host disagree on the agents contract.`,\n    );\n  }\n\n  return { status: 'ok', data: parsed.data };\n}\n\nfunction readIssues(value: unknown): AgentTemplateIssue[] {\n  if (!Array.isArray(value)) return [];\n  return value.flatMap((issue) => {\n    const parsed = AgentTemplateIssueSchema.safeParse(issue);\n    return parsed.success ? [parsed.data] : [];\n  });\n}\n\nasync function readOptionalJson(\n  response: Response,\n): Promise<Record<string, unknown>> {\n  try {\n    const parsed: unknown = await response.json();\n    return typeof parsed === 'object' && parsed !== null\n      ? (parsed as Record<string, unknown>)\n      : {};\n  } catch {\n    return {};\n  }\n}\n\nfunction isRedirect(status: number): boolean {\n  return status >= 300 && status < 400;\n}\n\nfunction str(value: unknown): string | null {\n  return typeof value === 'string' && value.length > 0 ? value : null;\n}\n"]}

package/dist/catalog-api.d.ts

@@ -0,0 +1,26 @@
+import { type SourceCatalog } from '@ekanos/integration-schema';
+/**
+ * The CLI's client for the Source catalog (plan 239.0).
+ *
+ * ---------------------------------------------------------------------------
+ * WIRE CONTRACT — `SourceCatalogSchema` in `@ekanos/integration-schema`,
+ * which the host's `/api/partner/catalog` route builds and this parses.
+ *
+ *   GET /api/partner/catalog?source=<slug|id>[&product=<slug>]
+ *       [Authorization: Bearer <access_token>]
+ *     → 200 { ok: true, data: SourceCatalog }
+ *     → 401 / 3xx                        refresh once and retry
+ *     → 403 { code: "MFA_REQUIRED" | "FORBIDDEN" }
+ *     → 404 { code: "SOURCE_NOT_FOUND" | "PRODUCT_NOT_FOUND" }
+ * ---------------------------------------------------------------------------
+ */
+export type FetchSourceCatalogResult = {
+    status: 'ok';
+    catalog: SourceCatalog;
+} | {
+    status: 'unauthorized';
+};
+export declare function fetchSourceCatalog(host: string, accessToken: string, query: {
+    source: string;
+    product?: string;
+}): Promise<FetchSourceCatalogResult>;

package/dist/catalog-api.js

@@ -0,0 +1,61 @@
+import { SourceCatalogSchema, } from '@ekanos/integration-schema';
+import { request } from './auth/ekanos-api.js';
+import { authRequiredError, forbiddenError, networkError, notFoundError, } from './errors.js';
+export async function fetchSourceCatalog(host, accessToken, query) {
+    var _a;
+    const params = new URLSearchParams({ source: query.source });
+    if (query.product)
+        params.set('product', query.product);
+    const response = await request(`${host}/api/partner/catalog?${params.toString()}`, {
+        method: 'GET',
+        headers: {
+            accept: 'application/json',
+            authorization: `Bearer ${accessToken}`,
+        },
+    });
+    if (response.status === 401 || isRedirect(response.status)) {
+        return { status: 'unauthorized' };
+    }
+    const body = await readOptionalJson(response);
+    const code = str(body.code);
+    const message = str(body.error);
+    if (response.status === 403 && code === 'MFA_REQUIRED') {
+        throw authRequiredError(message !== null && message !== void 0 ? message : `${host} requires multi-factor authentication.`, `Complete MFA in the browser, then run "ekanos login" again.`);
+    }
+    if (response.status === 403) {
+        throw forbiddenError(message !== null && message !== void 0 ? message : `No seat on "${query.source}".`, `Run "ekanos sources" to list the sources you hold a seat on.`);
+    }
+    if (response.status === 404) {
+        throw notFoundError(message !== null && message !== void 0 ? message : `"${(_a = query.product) !== null && _a !== void 0 ? _a : query.source}" was not found.`, code === 'PRODUCT_NOT_FOUND'
+            ? `Run "ekanos catalog" to list the products this Source can use.`
+            : `Run "ekanos sources" to list the sources you hold a seat on.`);
+    }
+    if (!response.ok) {
+        throw networkError(`${host}/api/partner/catalog responded ${response.status}.`, response.status >= 500
+            ? `The Ekanos deployment returned a server error. Retry shortly.`
+            : `Confirm the host runs a build that includes the catalog route.`);
+    }
+    const parsed = SourceCatalogSchema.safeParse(body.data);
+    if (!parsed.success) {
+        throw networkError(`${host}/api/partner/catalog answered in a shape this CLI does not read.`, `Run "ekanos upgrade" — the CLI and the host disagree on the catalog contract.`);
+    }
+    return { status: 'ok', catalog: parsed.data };
+}
+async function readOptionalJson(response) {
+    try {
+        const parsed = await response.json();
+        return typeof parsed === 'object' && parsed !== null
+            ? parsed
+            : {};
+    }
+    catch (_a) {
+        return {};
+    }
+}
+function isRedirect(status) {
+    return status >= 300 && status < 400;
+}
+function str(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+//# sourceMappingURL=catalog-api.js.map

package/dist/catalog-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-api.js","sourceRoot":"","sources":["../src/catalog-api.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  type SourceCatalog,\n  SourceCatalogSchema,\n} from '@ekanos/integration-schema';\n\nimport { request } from './auth/ekanos-api';\nimport {\n  authRequiredError,\n  forbiddenError,\n  networkError,\n  notFoundError,\n} from './errors';\n\n/**\n * The CLI's client for the Source catalog (plan 239.0).\n *\n * ---------------------------------------------------------------------------\n * WIRE CONTRACT — `SourceCatalogSchema` in `@ekanos/integration-schema`,\n * which the host's `/api/partner/catalog` route builds and this parses.\n *\n *   GET /api/partner/catalog?source=<slug|id>[&product=<slug>]\n *       [Authorization: Bearer <access_token>]\n *     → 200 { ok: true, data: SourceCatalog }\n *     → 401 / 3xx                        refresh once and retry\n *     → 403 { code: \"MFA_REQUIRED\" | \"FORBIDDEN\" }\n *     → 404 { code: \"SOURCE_NOT_FOUND\" | \"PRODUCT_NOT_FOUND\" }\n * ---------------------------------------------------------------------------\n */\n\nexport type FetchSourceCatalogResult =\n  | { status: 'ok'; catalog: SourceCatalog }\n  | { status: 'unauthorized' };\n\nexport async function fetchSourceCatalog(\n  host: string,\n  accessToken: string,\n  query: { source: string; product?: string },\n): Promise<FetchSourceCatalogResult> {\n  const params = new URLSearchParams({ source: query.source });\n  if (query.product) params.set('product', query.product);\n\n  const response = await request(\n    `${host}/api/partner/catalog?${params.toString()}`,\n    {\n      method: 'GET',\n      headers: {\n        accept: 'application/json',\n        authorization: `Bearer ${accessToken}`,\n      },\n    },\n  );\n\n  if (response.status === 401 || isRedirect(response.status)) {\n    return { status: 'unauthorized' };\n  }\n\n  const body = await readOptionalJson(response);\n  const code = str(body.code);\n  const message = str(body.error);\n\n  if (response.status === 403 && code === 'MFA_REQUIRED') {\n    throw authRequiredError(\n      message ?? `${host} requires multi-factor authentication.`,\n      `Complete MFA in the browser, then run \"ekanos login\" again.`,\n    );\n  }\n\n  if (response.status === 403) {\n    throw forbiddenError(\n      message ?? `No seat on \"${query.source}\".`,\n      `Run \"ekanos sources\" to list the sources you hold a seat on.`,\n    );\n  }\n\n  if (response.status === 404) {\n    throw notFoundError(\n      message ?? `\"${query.product ?? query.source}\" was not found.`,\n      code === 'PRODUCT_NOT_FOUND'\n        ? `Run \"ekanos catalog\" to list the products this Source can use.`\n        : `Run \"ekanos sources\" to list the sources you hold a seat on.`,\n    );\n  }\n\n  if (!response.ok) {\n    throw networkError(\n      `${host}/api/partner/catalog responded ${response.status}.`,\n      response.status >= 500\n        ? `The Ekanos deployment returned a server error. Retry shortly.`\n        : `Confirm the host runs a build that includes the catalog route.`,\n    );\n  }\n\n  const parsed = SourceCatalogSchema.safeParse(body.data);\n  if (!parsed.success) {\n    throw networkError(\n      `${host}/api/partner/catalog answered in a shape this CLI does not read.`,\n      `Run \"ekanos upgrade\" — the CLI and the host disagree on the catalog contract.`,\n    );\n  }\n\n  return { status: 'ok', catalog: parsed.data };\n}\n\nasync function readOptionalJson(\n  response: Response,\n): Promise<Record<string, unknown>> {\n  try {\n    const parsed: unknown = await response.json();\n    return typeof parsed === 'object' && parsed !== null\n      ? (parsed as Record<string, unknown>)\n      : {};\n  } catch {\n    return {};\n  }\n}\n\nfunction isRedirect(status: number): boolean {\n  return status >= 300 && status < 400;\n}\n\nfunction str(value: unknown): string | null {\n  return typeof value === 'string' && value.length > 0 ? value : null;\n}\n"]}

package/dist/commands/agents.d.ts

@@ -0,0 +1,49 @@
+import { type AgentTemplateBody } from '@ekanos/integration-schema';
+import type { CliContext } from '../context.js';
+import type { ExitCode } from '../exit-codes.js';
+export declare const AGENTS_SUBCOMMANDS: readonly ['list', 'show', 'pull', 'apply', 'publish', 'rollback'];
+/** The file `pull` writes and `apply` reads, inside an agent's directory. */
+export declare const AGENT_FILE = "agent.json";
+/** Instructions as Markdown, beside it. Used when `agent.json` has none. */
+export declare const AGENT_INSTRUCTIONS_FILE = "AGENT.md";
+export interface AgentsArgs {
+    host?: string;
+    source?: string;
+    subcommand?: string;
+    /** A template key, or for `apply` a file or directory. */
+    target?: string;
+    /** `publish` / `rollback`: the version to make the one teams run. */
+    to?: string;
+    baseVersion?: string;
+    overwrite: boolean;
+    out?: string;
+    yes: boolean;
+    dir: string;
+    env: Record<string, string | undefined>;
+    stdinIsTTY?: boolean;
+    confirm?: (question: string) => Promise<boolean>;
+}
+/**
+ * `agents` — the Source's agent templates (plan 239.0 / 239.2). Ekanos holds
+ * them; nothing here is deployed. `apply` stores a new version (a draft
+ * until published), `publish` makes a version the one every team runs,
+ * `rollback` publishes an older one. `pull` writes a template out as
+ * `agent.json` + `AGENT.md` for review or Git, and `apply` reads the same
+ * layout back.
+ */
+export declare function runAgents(ctx: CliContext, args: AgentsArgs): Promise<ExitCode>;
+interface AgentInput {
+    key: string;
+    body: AgentTemplateBody;
+    baseVersion: number | null;
+    /** The agent.json read, when there was one, so the new version is recorded in it. */
+    file: string | null;
+}
+/**
+ * Read `apply`'s input: a directory holding `agent.json` (and optionally
+ * `AGENT.md`), or a `.json` file. The key is the file's `key`, else the
+ * directory's name. `baseVersion` in the file is the version it was pulled
+ * or last applied at — what the host checks for a concurrent change.
+ */
+export declare function readAgentInput(target: string | undefined, cwd: string): AgentInput;
+export {};