@shogo-ai/cli 1.4.1

package/dist/deploy.cjs

@@ -0,0 +1,255 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/deploy.ts
+var deploy_exports = {};
+__export(deploy_exports, {
+  AGENT_NAME_PATTERN: () => AGENT_NAME_PATTERN,
+  buildSyncPayload: () => buildSyncPayload,
+  normalizeToolEntry: () => normalizeToolEntry,
+  runDeploy: () => runDeploy,
+  validateManifest: () => validateManifest
+});
+module.exports = __toCommonJS(deploy_exports);
+var AGENT_NAME_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
+var KNOWN_KEYS = /* @__PURE__ */ new Set([
+  "systemPrompt",
+  "tools",
+  "characterName",
+  "displayName",
+  "voiceId",
+  "firstMessage",
+  "model"
+]);
+function validateManifest(raw) {
+  const issues = [];
+  if (raw == null) return { agents: {}, issues };
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    issues.push({
+      path: "agents",
+      message: "`agents` must be an object keyed by agent name"
+    });
+    return { agents: {}, issues };
+  }
+  const agents = {};
+  for (const [name, value] of Object.entries(raw)) {
+    if (!AGENT_NAME_PATTERN.test(name)) {
+      issues.push({
+        path: `agents.${name}`,
+        message: `agent name must match ${AGENT_NAME_PATTERN}`
+      });
+      continue;
+    }
+    if (value == null || typeof value !== "object" || Array.isArray(value)) {
+      issues.push({
+        path: `agents.${name}`,
+        message: "value must be an object"
+      });
+      continue;
+    }
+    const entry = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (!KNOWN_KEYS.has(k)) {
+        issues.push({
+          path: `agents.${name}.${k}`,
+          message: `unknown field; supported: ${[...KNOWN_KEYS].join(", ")}`
+        });
+        continue;
+      }
+      if (k === "tools") {
+        if (!Array.isArray(v)) {
+          issues.push({
+            path: `agents.${name}.tools`,
+            message: "must be an array of strings or { name, description?, inputSchema? } objects"
+          });
+          continue;
+        }
+        const tools = [];
+        const seenNames = /* @__PURE__ */ new Set();
+        let valid = true;
+        for (let i = 0; i < v.length; i++) {
+          const t = v[i];
+          if (typeof t === "string") {
+            if (t.length === 0) {
+              issues.push({
+                path: `agents.${name}.tools[${i}]`,
+                message: "tool name must be a non-empty string"
+              });
+              valid = false;
+              continue;
+            }
+            if (seenNames.has(t)) {
+              issues.push({
+                path: `agents.${name}.tools[${i}]`,
+                message: `duplicate tool name '${t}'`
+              });
+              valid = false;
+              continue;
+            }
+            seenNames.add(t);
+            tools.push(t);
+            continue;
+          }
+          if (t == null || typeof t !== "object" || Array.isArray(t)) {
+            issues.push({
+              path: `agents.${name}.tools[${i}]`,
+              message: "tools entries must be a string or { name, description?, inputSchema? }"
+            });
+            valid = false;
+            continue;
+          }
+          const obj = t;
+          if (typeof obj.name !== "string" || obj.name.length === 0) {
+            issues.push({
+              path: `agents.${name}.tools[${i}].name`,
+              message: "name is required and must be a non-empty string"
+            });
+            valid = false;
+            continue;
+          }
+          if (seenNames.has(obj.name)) {
+            issues.push({
+              path: `agents.${name}.tools[${i}]`,
+              message: `duplicate tool name '${obj.name}'`
+            });
+            valid = false;
+            continue;
+          }
+          if (obj.description !== void 0 && typeof obj.description !== "string") {
+            issues.push({
+              path: `agents.${name}.tools[${i}].description`,
+              message: "description must be a string"
+            });
+            valid = false;
+            continue;
+          }
+          if (obj.inputSchema !== void 0 && (obj.inputSchema === null || typeof obj.inputSchema !== "object" || Array.isArray(obj.inputSchema))) {
+            issues.push({
+              path: `agents.${name}.tools[${i}].inputSchema`,
+              message: "inputSchema must be a JSON Schema object"
+            });
+            valid = false;
+            continue;
+          }
+          seenNames.add(obj.name);
+          const descriptor = { name: obj.name };
+          if (typeof obj.description === "string") {
+            descriptor.description = obj.description;
+          }
+          if (obj.inputSchema !== void 0) {
+            descriptor.inputSchema = obj.inputSchema;
+          }
+          tools.push(descriptor);
+        }
+        if (valid) entry.tools = tools;
+        continue;
+      }
+      if (typeof v !== "string") {
+        issues.push({
+          path: `agents.${name}.${k}`,
+          message: "must be a string"
+        });
+        continue;
+      }
+      ;
+      entry[k] = v;
+    }
+    if (entry.voiceId && !entry.firstMessage) {
+      issues.push({
+        path: `agents.${name}.firstMessage`,
+        message: "voiceId is set; consider providing firstMessage so the agent has a greeting"
+      });
+    }
+    agents[name] = entry;
+  }
+  return { agents, issues };
+}
+function normalizeToolEntry(entry) {
+  if (typeof entry === "string") return { name: entry };
+  const out = { name: entry.name };
+  if (entry.description !== void 0) out.description = entry.description;
+  if (entry.inputSchema !== void 0) out.inputSchema = entry.inputSchema;
+  return out;
+}
+function buildSyncPayload(opts) {
+  const out = { agents: {}, prune: opts.prune, dryRun: opts.dryRun };
+  for (const [name, entry] of Object.entries(opts.manifest)) {
+    const a = {};
+    if (entry.systemPrompt !== void 0) a.systemPrompt = entry.systemPrompt;
+    if (entry.tools !== void 0) {
+      a.tools = entry.tools.map(normalizeToolEntry);
+    }
+    if (entry.characterName !== void 0) a.characterName = entry.characterName;
+    if (entry.displayName !== void 0) a.displayName = entry.displayName;
+    if (entry.voiceId !== void 0) a.voiceId = entry.voiceId;
+    if (entry.firstMessage !== void 0) a.firstMessage = entry.firstMessage;
+    if (entry.model !== void 0) a.model = entry.model;
+    out.agents[name] = a;
+  }
+  return out;
+}
+function resolveDeployHeaders(options) {
+  const headers = {
+    "content-type": "application/json"
+  };
+  const auth = options.auth ?? (options.shogoApiKey ? { kind: "apiKey", apiKey: options.shogoApiKey } : void 0);
+  if (!auth) {
+    throw new Error(
+      'runDeploy: missing auth \u2014 pass `auth: { kind: "apiKey", apiKey }` or `auth: { kind: "runtimeToken", token }`'
+    );
+  }
+  if (auth.kind === "apiKey") {
+    headers.authorization = `Bearer ${auth.apiKey}`;
+  } else {
+    headers["x-runtime-token"] = auth.token;
+  }
+  return headers;
+}
+async function runDeploy(options) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new Error("runDeploy: global fetch is unavailable; pass options.fetchImpl");
+  }
+  const url = `${options.apiUrl.replace(/\/+$/, "")}/api/projects/${encodeURIComponent(options.projectId)}/agents/sync`;
+  const payload = buildSyncPayload({
+    manifest: options.manifest,
+    prune: options.prune,
+    dryRun: options.dryRun
+  });
+  const res = await fetchImpl(url, {
+    method: "POST",
+    headers: resolveDeployHeaders(options),
+    body: JSON.stringify(payload)
+  });
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {
+  }
+  return { status: res.status, body };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AGENT_NAME_PATTERN,
+  buildSyncPayload,
+  normalizeToolEntry,
+  runDeploy,
+  validateManifest
+});
+//# sourceMappingURL=deploy.cjs.map

package/dist/deploy.d.cts

@@ -0,0 +1,168 @@
+/**
+ * `shogo deploy` — reconcile `shogo.config.json#agents` with the
+ * project's cloud-side `project_agents` table.
+ *
+ * The CLI is a thin wrapper around
+ * `POST /api/projects/:projectId/agents/sync` (apps/api). All
+ * validation of the manifest happens once on the client (here) and
+ * once on the server (`projectAgentSync.service.ts`). The server is
+ * still authoritative — but pushing validation to the CLI gives users
+ * helpful errors before any network round-trip and makes the deploy
+ * command CI-friendly.
+ *
+ * Pure module: no I/O at import time. Side effects (fetch, console)
+ * are reachable only through `runDeploy`. The validator and payload
+ * builder are exported so unit tests can exercise them without
+ * spinning up a network mock.
+ */
+/**
+ * A tool the named agent is permitted to invoke. Either form is
+ * accepted in `shogo.config.json`:
+ *
+ *   - `"add_memory"` — name-only sugar; the consumer's `clientTools`
+ *     map is responsible for declaring the schema to the model. Used
+ *     for backwards-compat with manifests written before tool schemas
+ *     existed.
+ *   - `{ name, description?, inputSchema? }` — full descriptor. The
+ *     manifest becomes the source of truth: ElevenLabs gets the same
+ *     schema (so the voice agent can `tool-call`), and the chat route
+ *     declares it to `streamText` directly. `clientTools` only needs
+ *     to provide the handler.
+ */
+type AgentToolEntry = string | {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+};
+/**
+ * Normalized tool descriptor shipped on the wire to
+ * `POST /api/projects/:id/agents/sync`. String sugar from the manifest
+ * is expanded to `{ name }` here so the API receives a single shape.
+ */
+interface ToolDescriptor {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+}
+interface AgentManifestEntry {
+    systemPrompt?: string;
+    /**
+     * Tools the named agent is permitted to invoke. See {@link AgentToolEntry}.
+     * After validation the descriptors are normalized to
+     * {@link ToolDescriptor}; `manifest.tools` keeps the user's original
+     * shape so downstream code can preserve sugar in error messages.
+     */
+    tools?: AgentToolEntry[];
+    characterName?: string;
+    displayName?: string;
+    voiceId?: string;
+    firstMessage?: string;
+    /**
+     * Chat-side model id (forwarded to the AI proxy / Anthropic
+     * directly). Falls back to the project's default chat model when
+     * unset.
+     */
+    model?: string;
+}
+interface AgentsManifest {
+    [name: string]: AgentManifestEntry;
+}
+/** Allowed agent name shape; server enforces the same regex. */
+declare const AGENT_NAME_PATTERN: RegExp;
+interface ValidationIssue {
+    /** Dot-path to the offending field, e.g. `agents.architect.tools[2]`. */
+    path: string;
+    message: string;
+}
+interface ValidatedManifest {
+    agents: AgentsManifest;
+    issues: ValidationIssue[];
+}
+/**
+ * Validate the `agents` block of a parsed `shogo.config.json`.
+ * Returns the trimmed manifest plus a list of issues. The deploy
+ * command treats a non-empty issues list as a hard failure unless
+ * the caller passes `--force` (not implemented here; the CLI layer
+ * decides).
+ */
+declare function validateManifest(raw: unknown): ValidatedManifest;
+interface BuildSyncPayloadOptions {
+    manifest: AgentsManifest;
+    prune: boolean;
+    dryRun: boolean;
+}
+/** Wire payload for `POST /api/projects/:id/agents/sync`. */
+interface SyncPayload {
+    agents: Record<string, {
+        systemPrompt?: string;
+        tools?: ToolDescriptor[];
+        characterName?: string;
+        displayName?: string;
+        voiceId?: string;
+        firstMessage?: string;
+        model?: string;
+    }>;
+    prune: boolean;
+    dryRun: boolean;
+}
+/** Expand string sugar into a normalized {@link ToolDescriptor}. */
+declare function normalizeToolEntry(entry: AgentToolEntry): ToolDescriptor;
+/**
+ * Convert a CLI-side manifest to the wire shape the API expects. The
+ * shape matches `apps/api/src/services/projectAgentSync.service.ts`.
+ *
+ * Tool entries are normalized to `ToolDescriptor[]` here — the API
+ * never sees the string sugar.
+ */
+declare function buildSyncPayload(opts: BuildSyncPayloadOptions): SyncPayload;
+/**
+ * Two ways to authenticate a deploy:
+ *
+ *   - `apiKey` — `Authorization: Bearer shogo_sk_*`. The default for
+ *     a developer running `shogo deploy` from their own machine.
+ *   - `runtimeToken` — `x-runtime-token: <token>`. The path used by
+ *     `shogo dev` preflight inside a warm pod, where the pod's
+ *     runtime token is already in env (`RUNTIME_AUTH_SECRET`).
+ *
+ * The server enforces that runtime-token deploys are scoped to the
+ * token's own project (no cross-project mutations).
+ */
+type DeployAuth = {
+    kind: 'apiKey';
+    apiKey: string;
+} | {
+    kind: 'runtimeToken';
+    token: string;
+};
+interface RunDeployOptions {
+    apiUrl: string;
+    projectId: string;
+    manifest: AgentsManifest;
+    prune: boolean;
+    dryRun: boolean;
+    /**
+     * Authentication for the deploy request. Either `{ kind: 'apiKey',
+     * apiKey }` (developer flow) or `{ kind: 'runtimeToken', token }`
+     * (warm-pod preflight flow).
+     *
+     * Legacy callers may still pass `shogoApiKey` directly — it is
+     * promoted to `auth: { kind: 'apiKey', apiKey: shogoApiKey }` for
+     * backwards compatibility.
+     */
+    auth?: DeployAuth;
+    /** @deprecated Pass `auth: { kind: 'apiKey', apiKey }` instead. */
+    shogoApiKey?: string;
+    fetchImpl?: typeof fetch;
+}
+interface RunDeployResult {
+    status: number;
+    body: unknown;
+}
+/**
+ * Issue the sync request. Caller is responsible for resolving
+ * `apiUrl`, `projectId`, and `auth` (typically from the environment +
+ * `shogo.config.json`).
+ */
+declare function runDeploy(options: RunDeployOptions): Promise<RunDeployResult>;
+
+export { AGENT_NAME_PATTERN, type AgentManifestEntry, type AgentToolEntry, type AgentsManifest, type BuildSyncPayloadOptions, type DeployAuth, type RunDeployOptions, type RunDeployResult, type SyncPayload, type ToolDescriptor, type ValidatedManifest, type ValidationIssue, buildSyncPayload, normalizeToolEntry, runDeploy, validateManifest };

package/dist/deploy.d.ts

@@ -0,0 +1,168 @@
+/**
+ * `shogo deploy` — reconcile `shogo.config.json#agents` with the
+ * project's cloud-side `project_agents` table.
+ *
+ * The CLI is a thin wrapper around
+ * `POST /api/projects/:projectId/agents/sync` (apps/api). All
+ * validation of the manifest happens once on the client (here) and
+ * once on the server (`projectAgentSync.service.ts`). The server is
+ * still authoritative — but pushing validation to the CLI gives users
+ * helpful errors before any network round-trip and makes the deploy
+ * command CI-friendly.
+ *
+ * Pure module: no I/O at import time. Side effects (fetch, console)
+ * are reachable only through `runDeploy`. The validator and payload
+ * builder are exported so unit tests can exercise them without
+ * spinning up a network mock.
+ */
+/**
+ * A tool the named agent is permitted to invoke. Either form is
+ * accepted in `shogo.config.json`:
+ *
+ *   - `"add_memory"` — name-only sugar; the consumer's `clientTools`
+ *     map is responsible for declaring the schema to the model. Used
+ *     for backwards-compat with manifests written before tool schemas
+ *     existed.
+ *   - `{ name, description?, inputSchema? }` — full descriptor. The
+ *     manifest becomes the source of truth: ElevenLabs gets the same
+ *     schema (so the voice agent can `tool-call`), and the chat route
+ *     declares it to `streamText` directly. `clientTools` only needs
+ *     to provide the handler.
+ */
+type AgentToolEntry = string | {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+};
+/**
+ * Normalized tool descriptor shipped on the wire to
+ * `POST /api/projects/:id/agents/sync`. String sugar from the manifest
+ * is expanded to `{ name }` here so the API receives a single shape.
+ */
+interface ToolDescriptor {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+}
+interface AgentManifestEntry {
+    systemPrompt?: string;
+    /**
+     * Tools the named agent is permitted to invoke. See {@link AgentToolEntry}.
+     * After validation the descriptors are normalized to
+     * {@link ToolDescriptor}; `manifest.tools` keeps the user's original
+     * shape so downstream code can preserve sugar in error messages.
+     */
+    tools?: AgentToolEntry[];
+    characterName?: string;
+    displayName?: string;
+    voiceId?: string;
+    firstMessage?: string;
+    /**
+     * Chat-side model id (forwarded to the AI proxy / Anthropic
+     * directly). Falls back to the project's default chat model when
+     * unset.
+     */
+    model?: string;
+}
+interface AgentsManifest {
+    [name: string]: AgentManifestEntry;
+}
+/** Allowed agent name shape; server enforces the same regex. */
+declare const AGENT_NAME_PATTERN: RegExp;
+interface ValidationIssue {
+    /** Dot-path to the offending field, e.g. `agents.architect.tools[2]`. */
+    path: string;
+    message: string;
+}
+interface ValidatedManifest {
+    agents: AgentsManifest;
+    issues: ValidationIssue[];
+}
+/**
+ * Validate the `agents` block of a parsed `shogo.config.json`.
+ * Returns the trimmed manifest plus a list of issues. The deploy
+ * command treats a non-empty issues list as a hard failure unless
+ * the caller passes `--force` (not implemented here; the CLI layer
+ * decides).
+ */
+declare function validateManifest(raw: unknown): ValidatedManifest;
+interface BuildSyncPayloadOptions {
+    manifest: AgentsManifest;
+    prune: boolean;
+    dryRun: boolean;
+}
+/** Wire payload for `POST /api/projects/:id/agents/sync`. */
+interface SyncPayload {
+    agents: Record<string, {
+        systemPrompt?: string;
+        tools?: ToolDescriptor[];
+        characterName?: string;
+        displayName?: string;
+        voiceId?: string;
+        firstMessage?: string;
+        model?: string;
+    }>;
+    prune: boolean;
+    dryRun: boolean;
+}
+/** Expand string sugar into a normalized {@link ToolDescriptor}. */
+declare function normalizeToolEntry(entry: AgentToolEntry): ToolDescriptor;
+/**
+ * Convert a CLI-side manifest to the wire shape the API expects. The
+ * shape matches `apps/api/src/services/projectAgentSync.service.ts`.
+ *
+ * Tool entries are normalized to `ToolDescriptor[]` here — the API
+ * never sees the string sugar.
+ */
+declare function buildSyncPayload(opts: BuildSyncPayloadOptions): SyncPayload;
+/**
+ * Two ways to authenticate a deploy:
+ *
+ *   - `apiKey` — `Authorization: Bearer shogo_sk_*`. The default for
+ *     a developer running `shogo deploy` from their own machine.
+ *   - `runtimeToken` — `x-runtime-token: <token>`. The path used by
+ *     `shogo dev` preflight inside a warm pod, where the pod's
+ *     runtime token is already in env (`RUNTIME_AUTH_SECRET`).
+ *
+ * The server enforces that runtime-token deploys are scoped to the
+ * token's own project (no cross-project mutations).
+ */
+type DeployAuth = {
+    kind: 'apiKey';
+    apiKey: string;
+} | {
+    kind: 'runtimeToken';
+    token: string;
+};
+interface RunDeployOptions {
+    apiUrl: string;
+    projectId: string;
+    manifest: AgentsManifest;
+    prune: boolean;
+    dryRun: boolean;
+    /**
+     * Authentication for the deploy request. Either `{ kind: 'apiKey',
+     * apiKey }` (developer flow) or `{ kind: 'runtimeToken', token }`
+     * (warm-pod preflight flow).
+     *
+     * Legacy callers may still pass `shogoApiKey` directly — it is
+     * promoted to `auth: { kind: 'apiKey', apiKey: shogoApiKey }` for
+     * backwards compatibility.
+     */
+    auth?: DeployAuth;
+    /** @deprecated Pass `auth: { kind: 'apiKey', apiKey }` instead. */
+    shogoApiKey?: string;
+    fetchImpl?: typeof fetch;
+}
+interface RunDeployResult {
+    status: number;
+    body: unknown;
+}
+/**
+ * Issue the sync request. Caller is responsible for resolving
+ * `apiUrl`, `projectId`, and `auth` (typically from the environment +
+ * `shogo.config.json`).
+ */
+declare function runDeploy(options: RunDeployOptions): Promise<RunDeployResult>;
+
+export { AGENT_NAME_PATTERN, type AgentManifestEntry, type AgentToolEntry, type AgentsManifest, type BuildSyncPayloadOptions, type DeployAuth, type RunDeployOptions, type RunDeployResult, type SyncPayload, type ToolDescriptor, type ValidatedManifest, type ValidationIssue, buildSyncPayload, normalizeToolEntry, runDeploy, validateManifest };

package/dist/deploy.js

@@ -0,0 +1,15 @@
+import {
+  AGENT_NAME_PATTERN,
+  buildSyncPayload,
+  normalizeToolEntry,
+  runDeploy,
+  validateManifest
+} from "./chunk-YYO73V5H.js";
+export {
+  AGENT_NAME_PATTERN,
+  buildSyncPayload,
+  normalizeToolEntry,
+  runDeploy,
+  validateManifest
+};
+//# sourceMappingURL=deploy.js.map