@ekanos/cli 0.15.0 → 0.17.0

package/dist/workflows-api.d.ts

@@ -0,0 +1,69 @@
+import { type TeamWorkflowApplied, type TeamWorkflowApplyRequest, type TeamWorkflowApprovalDecideRequest, type TeamWorkflowApprovalDecided, type TeamWorkflowApprovalList, type TeamWorkflowDetail, type TeamWorkflowList, type TeamWorkflowRunCancelled, type TeamWorkflowRunDetail, type TeamWorkflowRunList, type TeamWorkflowRunStartRequest, type TeamWorkflowRunStarted, type TeamWorkflowStatusChanged, type TeamWorkflowStatusRequest } from '@ekanos/integration-schema';
+/**
+ * The CLI's client for a team's workflows — `ekanos workflows`.
+ *
+ *   GET  /api/partner/teams/<team>/workflows                       → TeamWorkflowList
+ *   POST /api/partner/teams/<team>/workflows                       → TeamWorkflowApplied
+ *   GET  /api/partner/teams/<team>/workflows/<id>                  → TeamWorkflowDetail
+ *   POST /api/partner/teams/<team>/workflows/<id>/status           → TeamWorkflowStatusChanged
+ *   POST /api/partner/teams/<team>/workflows/<id>/runs             → TeamWorkflowRunStarted
+ *   GET  /api/partner/teams/<team>/workflows/runs                  → TeamWorkflowRunList
+ *   GET  /api/partner/teams/<team>/workflows/runs/<id>             → TeamWorkflowRunDetail
+ *   POST /api/partner/teams/<team>/workflows/runs/<id>/cancel      → TeamWorkflowRunCancelled
+ *   GET  /api/partner/teams/<team>/workflows/approvals             → TeamWorkflowApprovalList
+ *   POST /api/partner/teams/<team>/workflows/approvals/<id>        → TeamWorkflowApprovalDecided
+ *
+ * Every path carries `?source=<slug>`.
+ */
+export type WorkflowsApiResult<T> = {
+    status: 'ok';
+    data: T;
+} | {
+    status: 'unauthorized';
+}
+/** Activation stopped only on what Custom Code reaches: ask, then resend. */
+ | {
+    status: 'needs-access';
+    error: string;
+    codeAccess: CodeAccess[];
+};
+export interface CodeAccess {
+    stepId: string;
+    effect: 'read' | 'write';
+    egressHosts: string[];
+    tools: string[];
+    dependencies: string[];
+    reviewSummary: string | null;
+}
+interface TeamTarget {
+    source: string;
+    team: string;
+}
+export declare function listWorkflows(host: string, accessToken: string, target: TeamTarget & {
+    all: boolean;
+}): Promise<WorkflowsApiResult<TeamWorkflowList>>;
+export declare function showWorkflow(host: string, accessToken: string, target: TeamTarget & {
+    workflow: string;
+}): Promise<WorkflowsApiResult<TeamWorkflowDetail>>;
+export declare function applyWorkflow(host: string, accessToken: string, target: TeamTarget, body: TeamWorkflowApplyRequest): Promise<WorkflowsApiResult<TeamWorkflowApplied>>;
+export declare function setWorkflowStatus(host: string, accessToken: string, target: TeamTarget & {
+    workflow: string;
+}, body: TeamWorkflowStatusRequest): Promise<WorkflowsApiResult<TeamWorkflowStatusChanged>>;
+export declare function startWorkflowRun(host: string, accessToken: string, target: TeamTarget & {
+    workflow: string;
+}, body: TeamWorkflowRunStartRequest): Promise<WorkflowsApiResult<TeamWorkflowRunStarted>>;
+export declare function listWorkflowRuns(host: string, accessToken: string, target: TeamTarget & {
+    workflow?: string;
+    status?: string;
+}): Promise<WorkflowsApiResult<TeamWorkflowRunList>>;
+export declare function showWorkflowRun(host: string, accessToken: string, target: TeamTarget & {
+    runId: string;
+}): Promise<WorkflowsApiResult<TeamWorkflowRunDetail>>;
+export declare function cancelWorkflowRun(host: string, accessToken: string, target: TeamTarget & {
+    runId: string;
+}): Promise<WorkflowsApiResult<TeamWorkflowRunCancelled>>;
+export declare function listWorkflowApprovals(host: string, accessToken: string, target: TeamTarget): Promise<WorkflowsApiResult<TeamWorkflowApprovalList>>;
+export declare function decideWorkflowApproval(host: string, accessToken: string, target: TeamTarget & {
+    approvalId: string;
+}, body: TeamWorkflowApprovalDecideRequest): Promise<WorkflowsApiResult<TeamWorkflowApprovalDecided>>;
+export {};

package/dist/workflows-api.js

@@ -0,0 +1,182 @@
+import { TeamWorkflowAppliedSchema, TeamWorkflowApprovalDecidedSchema, TeamWorkflowApprovalListSchema, TeamWorkflowDetailSchema, TeamWorkflowListSchema, TeamWorkflowRunCancelledSchema, TeamWorkflowRunDetailSchema, TeamWorkflowRunListSchema, TeamWorkflowRunStartedSchema, TeamWorkflowStatusChangedSchema, } from '@ekanos/integration-schema';
+import { request } from './auth/ekanos-api.js';
+import { authRequiredError, forbiddenError, invalidStateError, networkError, notFoundError, usageError, validationError, } from './errors.js';
+const segment = encodeURIComponent;
+export function listWorkflows(host, accessToken, target) {
+    return call(host, accessToken, TeamWorkflowListSchema, {
+        method: 'GET',
+        path: base(target),
+        query: Object.assign({ source: target.source }, (target.all ? { all: '1' } : {})),
+    });
+}
+export function showWorkflow(host, accessToken, target) {
+    return call(host, accessToken, TeamWorkflowDetailSchema, {
+        method: 'GET',
+        path: `${base(target)}/${segment(target.workflow)}`,
+        query: { source: target.source },
+    });
+}
+export function applyWorkflow(host, accessToken, target, body) {
+    return call(host, accessToken, TeamWorkflowAppliedSchema, {
+        method: 'POST',
+        path: base(target),
+        query: { source: target.source },
+        body,
+    });
+}
+export function setWorkflowStatus(host, accessToken, target, body) {
+    return call(host, accessToken, TeamWorkflowStatusChangedSchema, {
+        method: 'POST',
+        path: `${base(target)}/${segment(target.workflow)}/status`,
+        query: { source: target.source },
+        body,
+    });
+}
+export function startWorkflowRun(host, accessToken, target, body) {
+    return call(host, accessToken, TeamWorkflowRunStartedSchema, {
+        method: 'POST',
+        path: `${base(target)}/${segment(target.workflow)}/runs`,
+        query: { source: target.source },
+        body,
+    });
+}
+export function listWorkflowRuns(host, accessToken, target) {
+    return call(host, accessToken, TeamWorkflowRunListSchema, {
+        method: 'GET',
+        path: `${base(target)}/runs`,
+        query: Object.assign(Object.assign({ source: target.source }, (target.workflow ? { workflow: target.workflow } : {})), (target.status ? { status: target.status } : {})),
+    });
+}
+export function showWorkflowRun(host, accessToken, target) {
+    return call(host, accessToken, TeamWorkflowRunDetailSchema, {
+        method: 'GET',
+        path: `${base(target)}/runs/${segment(target.runId)}`,
+        query: { source: target.source },
+    });
+}
+export function cancelWorkflowRun(host, accessToken, target) {
+    return call(host, accessToken, TeamWorkflowRunCancelledSchema, {
+        method: 'POST',
+        path: `${base(target)}/runs/${segment(target.runId)}/cancel`,
+        query: { source: target.source },
+    });
+}
+export function listWorkflowApprovals(host, accessToken, target) {
+    return call(host, accessToken, TeamWorkflowApprovalListSchema, {
+        method: 'GET',
+        path: `${base(target)}/approvals`,
+        query: { source: target.source },
+    });
+}
+export function decideWorkflowApproval(host, accessToken, target, body) {
+    return call(host, accessToken, TeamWorkflowApprovalDecidedSchema, {
+        method: 'POST',
+        path: `${base(target)}/approvals/${segment(target.approvalId)}`,
+        query: { source: target.source },
+        body,
+    });
+}
+function base(target) {
+    return `/api/partner/teams/${segment(target.team)}/workflows`;
+}
+async function call(host, accessToken, schema, init) {
+    const response = await request(`${host}${init.path}?${new URLSearchParams(init.query)}`, {
+        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 ||
+        (response.status >= 300 && response.status < 400)) {
+        return { status: 'unauthorized' };
+    }
+    const body = await readOptionalJson(response);
+    const code = typeof body.code === 'string' ? body.code : null;
+    const message = typeof body.error === 'string' && body.error ? body.error : null;
+    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 manages its teams' workflows."
+            : 'Run "ekanos sources" to list the sources you hold a seat on.');
+    }
+    if (response.status === 404) {
+        throw notFoundError(message !== null && message !== void 0 ? message : 'Not found.', code === 'TEAM_NOT_FOUND'
+            ? 'Run "ekanos teams list" to see the teams on this Source.'
+            : code === 'WORKFLOW_NOT_FOUND'
+                ? 'Run "ekanos workflows list --team <slug>" for the team\'s workflows (a member\'s personal workflow is theirs alone).'
+                : code === 'RUN_NOT_FOUND'
+                    ? 'Run "ekanos workflows runs list --team <slug>" for the team\'s runs.'
+                    : code === 'APPROVAL_NOT_FOUND'
+                        ? 'Run "ekanos workflows approvals list --team <slug>" for what is waiting.'
+                        : 'Run "ekanos sources" to list the sources you hold a seat on.');
+    }
+    if (response.status === 409 && code === 'CODE_ACCESS_NEEDS_APPROVAL') {
+        const details = Array.isArray(body.codeAccess) ? body.codeAccess : [];
+        return {
+            status: 'needs-access',
+            error: message !== null && message !== void 0 ? message : 'Custom Code access needs your approval.',
+            codeAccess: details.filter(isCodeAccess),
+        };
+    }
+    if (response.status === 422) {
+        throw validationError(message !== null && message !== void 0 ? message : 'The host refused the workflow definition.', code === 'INVALID_DEFINITION'
+            ? 'Fix the definition and apply it again; nothing was saved.'
+            : 'The stored definition no longer validates: fix it with "ekanos workflows apply <file> --update <id>".');
+    }
+    if (response.status === 409 || response.status === 502) {
+        throw invalidStateError(message !== null && message !== void 0 ? message : 'The host refused the request in its current state.', code === 'WORKFLOWS_EXPERIENCE_OFF'
+            ? 'Ask Ekanos to turn on Workflows for this Source: only a super-admin can ("ekanos sources products" shows it as off).'
+            : code === 'AMBIGUOUS_WORKFLOW'
+                ? 'Name it by id: "ekanos workflows list --team <slug>" shows each one\'s.'
+                : code === 'WORKFLOW_ARCHIVED'
+                    ? 'Restore it in the app first, or apply without --update to create a new draft.'
+                    : code === 'ALREADY_DECIDED' || code === 'APPROVAL_EXPIRED'
+                        ? 'Run "ekanos workflows approvals list --team <slug>" for what is still waiting.'
+                        : code === 'RUN_FINISHED'
+                            ? 'Nothing to stop. "ekanos workflows runs show <run-id> --team <slug>" shows how it ended.'
+                            : code === 'CANCEL_FAILED'
+                                ? 'Its status is reconciled automatically; check "ekanos workflows runs show <run-id>" shortly.'
+                                : code === 'RESUME_FAILED'
+                                    ? 'The decision is saved; the run picks it up shortly. Check with "ekanos workflows runs show <run-id>".'
+                                    : code === 'RUN_REFUSED'
+                                        ? 'A live run needs an active workflow ("ekanos workflows enable"); "--dry-run" rehearses a draft.'
+                                        : 'Run "ekanos workflows show <id> --team <slug>" for its status and what blocks it.');
+    }
+    if (response.status === 400) {
+        throw usageError(message !== null && message !== void 0 ? message : 'The host refused the request.', 'See "ekanos workflows --help".');
+    }
+    if (!response.ok) {
+        throw networkError(`${host}${init.path} responded ${response.status}.`, response.status >= 500
+            ? 'The Ekanos deployment returned a server error. Retry shortly.'
+            : 'Confirm the host runs a build that includes the workflows routes.');
+    }
+    const parsed = schema.safeParse(body.data);
+    if (!parsed.success) {
+        throw networkError(`${host}${init.path} answered in a shape this CLI does not read.`, 'Run "ekanos upgrade" — the CLI and the host disagree on the workflows contract.');
+    }
+    return { status: 'ok', data: parsed.data };
+}
+function isCodeAccess(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const entry = value;
+    return (typeof entry.stepId === 'string' &&
+        (entry.effect === 'read' || entry.effect === 'write') &&
+        Array.isArray(entry.egressHosts) &&
+        Array.isArray(entry.tools));
+}
+async function readOptionalJson(response) {
+    try {
+        const parsed = await response.json();
+        return typeof parsed === 'object' && parsed !== null
+            ? parsed
+            : {};
+    }
+    catch (_a) {
+        return {};
+    }
+}
+//# sourceMappingURL=workflows-api.js.map

package/dist/workflows-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows-api.js","sourceRoot":"","sources":["../src/workflows-api.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  type TeamWorkflowApplied,\n  TeamWorkflowAppliedSchema,\n  type TeamWorkflowApplyRequest,\n  type TeamWorkflowApprovalDecideRequest,\n  type TeamWorkflowApprovalDecided,\n  TeamWorkflowApprovalDecidedSchema,\n  type TeamWorkflowApprovalList,\n  TeamWorkflowApprovalListSchema,\n  type TeamWorkflowDetail,\n  TeamWorkflowDetailSchema,\n  type TeamWorkflowList,\n  TeamWorkflowListSchema,\n  type TeamWorkflowRunCancelled,\n  TeamWorkflowRunCancelledSchema,\n  type TeamWorkflowRunDetail,\n  TeamWorkflowRunDetailSchema,\n  type TeamWorkflowRunList,\n  TeamWorkflowRunListSchema,\n  type TeamWorkflowRunStartRequest,\n  type TeamWorkflowRunStarted,\n  TeamWorkflowRunStartedSchema,\n  type TeamWorkflowStatusChanged,\n  TeamWorkflowStatusChangedSchema,\n  type TeamWorkflowStatusRequest,\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 a team's workflows — `ekanos workflows`.\n *\n *   GET  /api/partner/teams/<team>/workflows                       → TeamWorkflowList\n *   POST /api/partner/teams/<team>/workflows                       → TeamWorkflowApplied\n *   GET  /api/partner/teams/<team>/workflows/<id>                  → TeamWorkflowDetail\n *   POST /api/partner/teams/<team>/workflows/<id>/status           → TeamWorkflowStatusChanged\n *   POST /api/partner/teams/<team>/workflows/<id>/runs             → TeamWorkflowRunStarted\n *   GET  /api/partner/teams/<team>/workflows/runs                  → TeamWorkflowRunList\n *   GET  /api/partner/teams/<team>/workflows/runs/<id>             → TeamWorkflowRunDetail\n *   POST /api/partner/teams/<team>/workflows/runs/<id>/cancel      → TeamWorkflowRunCancelled\n *   GET  /api/partner/teams/<team>/workflows/approvals             → TeamWorkflowApprovalList\n *   POST /api/partner/teams/<team>/workflows/approvals/<id>        → TeamWorkflowApprovalDecided\n *\n * Every path carries `?source=<slug>`.\n */\n\nexport type WorkflowsApiResult<T> =\n  | { status: 'ok'; data: T }\n  | { status: 'unauthorized' }\n  /** Activation stopped only on what Custom Code reaches: ask, then resend. */\n  | { status: 'needs-access'; error: string; codeAccess: CodeAccess[] };\n\nexport interface CodeAccess {\n  stepId: string;\n  effect: 'read' | 'write';\n  egressHosts: string[];\n  tools: string[];\n  dependencies: string[];\n  reviewSummary: string | null;\n}\n\ninterface TeamTarget {\n  source: string;\n  team: string;\n}\n\nconst segment = encodeURIComponent;\n\nexport function listWorkflows(\n  host: string,\n  accessToken: string,\n  target: TeamTarget & { all: boolean },\n): Promise<WorkflowsApiResult<TeamWorkflowList>> {\n  return call(host, accessToken, TeamWorkflowListSchema, {\n    method: 'GET',\n    path: base(target),\n    query: { source: target.source, ...(target.all ? { all: '1' } : {}) },\n  });\n}\n\nexport function showWorkflow(\n  host: string,\n  accessToken: string,\n  target: TeamTarget & { workflow: string },\n): Promise<WorkflowsApiResult<TeamWorkflowDetail>> {\n  return call(host, accessToken, TeamWorkflowDetailSchema, {\n    method: 'GET',\n    path: `${base(target)}/${segment(target.workflow)}`,\n    query: { source: target.source },\n  });\n}\n\nexport function applyWorkflow(\n  host: string,\n  accessToken: string,\n  target: TeamTarget,\n  body: TeamWorkflowApplyRequest,\n): Promise<WorkflowsApiResult<TeamWorkflowApplied>> {\n  return call(host, accessToken, TeamWorkflowAppliedSchema, {\n    method: 'POST',\n    path: base(target),\n    query: { source: target.source },\n    body,\n  });\n}\n\nexport function setWorkflowStatus(\n  host: string,\n  accessToken: string,\n  target: TeamTarget & { workflow: string },\n  body: TeamWorkflowStatusRequest,\n): Promise<WorkflowsApiResult<TeamWorkflowStatusChanged>> {\n  return call(host, accessToken, TeamWorkflowStatusChangedSchema, {\n    method: 'POST',\n    path: `${base(target)}/${segment(target.workflow)}/status`,\n    query: { source: target.source },\n    body,\n  });\n}\n\nexport function startWorkflowRun(\n  host: string,\n  accessToken: string,\n  target: TeamTarget & { workflow: string },\n  body: TeamWorkflowRunStartRequest,\n): Promise<WorkflowsApiResult<TeamWorkflowRunStarted>> {\n  return call(host, accessToken, TeamWorkflowRunStartedSchema, {\n    method: 'POST',\n    path: `${base(target)}/${segment(target.workflow)}/runs`,\n    query: { source: target.source },\n    body,\n  });\n}\n\nexport function listWorkflowRuns(\n  host: string,\n  accessToken: string,\n  target: TeamTarget & { workflow?: string; status?: string },\n): Promise<WorkflowsApiResult<TeamWorkflowRunList>> {\n  return call(host, accessToken, TeamWorkflowRunListSchema, {\n    method: 'GET',\n    path: `${base(target)}/runs`,\n    query: {\n      source: target.source,\n      ...(target.workflow ? { workflow: target.workflow } : {}),\n      ...(target.status ? { status: target.status } : {}),\n    },\n  });\n}\n\nexport function showWorkflowRun(\n  host: string,\n  accessToken: string,\n  target: TeamTarget & { runId: string },\n): Promise<WorkflowsApiResult<TeamWorkflowRunDetail>> {\n  return call(host, accessToken, TeamWorkflowRunDetailSchema, {\n    method: 'GET',\n    path: `${base(target)}/runs/${segment(target.runId)}`,\n    query: { source: target.source },\n  });\n}\n\nexport function cancelWorkflowRun(\n  host: string,\n  accessToken: string,\n  target: TeamTarget & { runId: string },\n): Promise<WorkflowsApiResult<TeamWorkflowRunCancelled>> {\n  return call(host, accessToken, TeamWorkflowRunCancelledSchema, {\n    method: 'POST',\n    path: `${base(target)}/runs/${segment(target.runId)}/cancel`,\n    query: { source: target.source },\n  });\n}\n\nexport function listWorkflowApprovals(\n  host: string,\n  accessToken: string,\n  target: TeamTarget,\n): Promise<WorkflowsApiResult<TeamWorkflowApprovalList>> {\n  return call(host, accessToken, TeamWorkflowApprovalListSchema, {\n    method: 'GET',\n    path: `${base(target)}/approvals`,\n    query: { source: target.source },\n  });\n}\n\nexport function decideWorkflowApproval(\n  host: string,\n  accessToken: string,\n  target: TeamTarget & { approvalId: string },\n  body: TeamWorkflowApprovalDecideRequest,\n): Promise<WorkflowsApiResult<TeamWorkflowApprovalDecided>> {\n  return call(host, accessToken, TeamWorkflowApprovalDecidedSchema, {\n    method: 'POST',\n    path: `${base(target)}/approvals/${segment(target.approvalId)}`,\n    query: { source: target.source },\n    body,\n  });\n}\n\nfunction base(target: TeamTarget): string {\n  return `/api/partner/teams/${segment(target.team)}/workflows`;\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    query: Record<string, string>;\n    body?: unknown;\n  },\n): Promise<WorkflowsApiResult<T>> {\n  const response = await request(\n    `${host}${init.path}?${new URLSearchParams(init.query)}`,\n    {\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\n  if (\n    response.status === 401 ||\n    (response.status >= 300 && response.status < 400)\n  ) {\n    return { status: 'unauthorized' };\n  }\n\n  const body = await readOptionalJson(response);\n  const code = typeof body.code === 'string' ? body.code : null;\n  const message =\n    typeof body.error === 'string' && body.error ? body.error : null;\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  if (response.status === 403) {\n    throw forbiddenError(\n      message ?? 'Not permitted on this Source.',\n      code === 'SOURCE_ADMIN_REQUIRED'\n        ? \"Only a Source admin manages its teams' workflows.\"\n        : 'Run \"ekanos sources\" to list the sources you hold a seat on.',\n    );\n  }\n  if (response.status === 404) {\n    throw notFoundError(\n      message ?? 'Not found.',\n      code === 'TEAM_NOT_FOUND'\n        ? 'Run \"ekanos teams list\" to see the teams on this Source.'\n        : code === 'WORKFLOW_NOT_FOUND'\n          ? 'Run \"ekanos workflows list --team <slug>\" for the team\\'s workflows (a member\\'s personal workflow is theirs alone).'\n          : code === 'RUN_NOT_FOUND'\n            ? 'Run \"ekanos workflows runs list --team <slug>\" for the team\\'s runs.'\n            : code === 'APPROVAL_NOT_FOUND'\n              ? 'Run \"ekanos workflows approvals list --team <slug>\" for what is waiting.'\n              : 'Run \"ekanos sources\" to list the sources you hold a seat on.',\n    );\n  }\n  if (response.status === 409 && code === 'CODE_ACCESS_NEEDS_APPROVAL') {\n    const details = Array.isArray(body.codeAccess) ? body.codeAccess : [];\n    return {\n      status: 'needs-access',\n      error: message ?? 'Custom Code access needs your approval.',\n      codeAccess: details.filter(isCodeAccess),\n    };\n  }\n  if (response.status === 422) {\n    throw validationError(\n      message ?? 'The host refused the workflow definition.',\n      code === 'INVALID_DEFINITION'\n        ? 'Fix the definition and apply it again; nothing was saved.'\n        : 'The stored definition no longer validates: fix it with \"ekanos workflows apply <file> --update <id>\".',\n    );\n  }\n  if (response.status === 409 || response.status === 502) {\n    throw invalidStateError(\n      message ?? 'The host refused the request in its current state.',\n      code === 'WORKFLOWS_EXPERIENCE_OFF'\n        ? 'Ask Ekanos to turn on Workflows for this Source: only a super-admin can (\"ekanos sources products\" shows it as off).'\n        : code === 'AMBIGUOUS_WORKFLOW'\n          ? 'Name it by id: \"ekanos workflows list --team <slug>\" shows each one\\'s.'\n          : code === 'WORKFLOW_ARCHIVED'\n            ? 'Restore it in the app first, or apply without --update to create a new draft.'\n            : code === 'ALREADY_DECIDED' || code === 'APPROVAL_EXPIRED'\n              ? 'Run \"ekanos workflows approvals list --team <slug>\" for what is still waiting.'\n              : code === 'RUN_FINISHED'\n                ? 'Nothing to stop. \"ekanos workflows runs show <run-id> --team <slug>\" shows how it ended.'\n                : code === 'CANCEL_FAILED'\n                  ? 'Its status is reconciled automatically; check \"ekanos workflows runs show <run-id>\" shortly.'\n                  : code === 'RESUME_FAILED'\n                    ? 'The decision is saved; the run picks it up shortly. Check with \"ekanos workflows runs show <run-id>\".'\n                    : code === 'RUN_REFUSED'\n                      ? 'A live run needs an active workflow (\"ekanos workflows enable\"); \"--dry-run\" rehearses a draft.'\n                      : 'Run \"ekanos workflows show <id> --team <slug>\" for its status and what blocks it.',\n    );\n  }\n  if (response.status === 400) {\n    throw usageError(\n      message ?? 'The host refused the request.',\n      'See \"ekanos workflows --help\".',\n    );\n  }\n  if (!response.ok) {\n    throw networkError(\n      `${host}${init.path} 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 workflows routes.',\n    );\n  }\n\n  const parsed = schema.safeParse(body.data);\n  if (!parsed.success) {\n    throw networkError(\n      `${host}${init.path} answered in a shape this CLI does not read.`,\n      'Run \"ekanos upgrade\" — the CLI and the host disagree on the workflows contract.',\n    );\n  }\n  return { status: 'ok', data: parsed.data };\n}\n\nfunction isCodeAccess(value: unknown): value is CodeAccess {\n  if (typeof value !== 'object' || value === null) return false;\n  const entry = value as Record<string, unknown>;\n  return (\n    typeof entry.stepId === 'string' &&\n    (entry.effect === 'read' || entry.effect === 'write') &&\n    Array.isArray(entry.egressHosts) &&\n    Array.isArray(entry.tools)\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"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekanos/cli",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "private": false,
   "description": "The Ekanos partner toolchain CLI: scaffold, validate, and test an Ekanos integration against the published @ekanos packages. Agent-native — every verb speaks JSON with a stable exit-code taxonomy.",
   "keywords": [
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@clack/prompts": "1.7.0",
-    "@ekanos/integration-schema": "0.17.0",
+    "@ekanos/integration-schema": "0.19.0",
     "esbuild": "0.28.1",
     "picocolors": "1.1.1"
   },
@@ -44,7 +44,7 @@
     "@types/node": "25.0.1",
     "typescript": "^7.0.2",
     "vitest": "4.1.10",
-    "zod": "4.6.5"
+    "zod": "4.6.7"
   },
   "peerDependencies": {
     "zod": "^3.25.76 || ^4.0.0"

package/templates/AGENTS.md.tmpl

@@ -431,10 +431,12 @@ Icons are Font Awesome glyph names via `@ekanos/ui/icon`. This generated shell l
 (`@fortawesome/fontawesome-free`) — a much smaller set than the Pro kit Ekanos
 itself runs — so a name that's Pro-only (or just mistyped) renders a
 circle-question disc instead of vanishing, and dev builds `console.warn` once
-per name to catch it before a screenshot review does. `fa-light` / `fa-duotone`
-/ `fa-thin` are rewritten to `fa-solid`, the one weight Free ships, so author
-`fa-light` anyway — it degrades harmlessly today, and the intended weight
-survives if this host ever loads Pro instead. Verify a glyph name against the
+per name to catch it before a screenshot review does. Write icon names
+family-less (`fa-gear`, not `fa-light fa-gear`): the host's theme picks the
+family, so a Source's icon style reaches your icons too, and
+`design/no-default-icon-family` rejects `fa-light` / `fa-regular`. On Free,
+families it lacks (`fa-light`, `fa-duotone`, `fa-thin`) still render as
+`fa-solid`. Verify a glyph name against the
 Free set (`pnpm --filter @ekanos/ui check:fa-free-names`, or
 https://fontawesome.com/search?o=r&s=solid,regular,brands) before relying on
 it looking like anything in particular.

package/templates/claude-skill.md.tmpl

@@ -30,7 +30,10 @@ and after upgrading `@ekanos/*` packages. The topic → URL map is in AGENTS.md.
 tools and agent triggers, and the steps left to set each one up. If a product
 already does what the user wants, propose setting it up (walk its
 `setupSteps`, naming who does each one) instead of building it again.
-`npx ekanos catalog <product> --json` shows one in full.
+`npx ekanos catalog <product> --json` shows one in full: each tool's
+`inputSchema` (so you can see which other tool returns an id a tool needs)
+and `connection` — who connects the product and whose connection an agent
+run uses.
 
 ## Managed agents live in Ekanos
 

package/templates/ekanos.json.tmpl

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

package/templates/experience/AGENTS.md.tmpl

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

package/templates/experience/ekanos.json.tmpl

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

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

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

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

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

package/templates/experience/gitignore.tmpl

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

package/templates/experience/package.json.tmpl

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

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

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

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

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

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

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

package/templates/experience/tsconfig.json.tmpl

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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