@cadcamfunv2/cadcamfun-nikcli-plugin 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# @cadcamfunv2/cadcamfun-nikcli-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A standalone [nikcli](https://github.com/) (terminal, another machine, CI) driving a **running CADCAMFUN**: the application's CAD/CAM
+action catalogue as nikcli tools. Same tool ids and descriptions as the in-app assistant (`cad`, `cad_edit`, `cam`, `cam_edit`,
+`library`, `parts`, `library_edit`, `memory`, `memory_edit`, `research`, `vcs`, `vcs_edit`), each carrying its actions behind `action`.
+
+The list is read from the running application (`GET /api/ai/actions`), so the plugin never holds a second copy of the catalogue.
+Calls go to `POST /api/ai/actions/invoke` and run the very tool definitions the embedded host registers, as the account that holds
+the token, in the project you name.
+
+## Use
+
+```jsonc
+// nikcli config
+{ "plugin": [["file:///path/to/packages/nikcli-plugin/src/index.ts", { "url": "http://127.0.0.1:43111", "token": "<launch token>", "projectId": "<project id>" }]] }
+```
+
+or `CADCAMFUN_URL`, `CADCAMFUN_TOKEN` and `CADCAMFUN_PROJECT` in the environment. Create the token in the application (Settings → AI → Standalone nikcli): it is for the open project, read-only or read-write, opens only
+the action bridge, expires, and can be revoked there. (The application's own launch token also works and opens everything; prefer a scoped one.)
+
+## What it will not do
+
+- **Delete or replace work** (`cad_edit` `delete`, `library_edit` `delete`, `vcs_edit` `restore`, ...): in the application the host asks
+  a person first, an outside client has no such prompt, and a `confirm: true` in the arguments is not an approval. The refusal says so.
+- **Delegate** to the specialist agents (`agent`): they run model sessions inside the application.
+- **Go beyond its scope**: a bridge token is for one project and, when read-only, reaches only read actions. The operator can narrow
+  further with nikcli policy statements in `<data dir>/ai/policy.json` (`bridge.use`, `tool.use`).
+
+## Compatibility
+
+`test/compat.test.ts` reads the shapes this package relies on (`Plugin`, `PluginModule`, `Hooks.tool`, `tool()`) from
+`@nikcli-ai/plugin`'s declarations in the repo's `.nikcli/` folder. `apps/sidecar/test/nikcli-plugin.test.ts` runs the plugin against the
+real sidecar routes.

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@cadcamfunv2/cadcamfun-nikcli-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Drive a running CADCAMFUN instance from a standalone nikcli: the application's CAD/CAM action catalogue as nikcli tools.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nikomatt69/cadcamfun.git",
+    "directory": "packages/nikcli-plugin"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "typecheck": "bun check -p tsconfig.json"
+  },
+  "dependencies": {
+    "zod": "^4.1.8"
+  }
+}

package/src/client.ts

@@ -0,0 +1,65 @@
+/**
+ * The HTTP face of the application, as a standalone nikcli reaches it: `GET /api/ai/actions` for the catalogue and
+ * `POST /api/ai/actions/invoke` for a call. The bearer token is the one the application's own windows use; it is sent on every
+ * request and never logged or put in an error.
+ */
+export interface BridgeTool {
+  readonly id: string
+  readonly description: string
+  readonly kind: "read" | "write" | "destructive"
+  readonly actions: ReadonlyArray<{ readonly id: string; readonly name: string; readonly kind: "read" | "write" | "destructive" }>
+  readonly parameters: Record<string, unknown>
+}
+
+export interface BridgeOptions {
+  /** Base URL of the running sidecar, e.g. `http://127.0.0.1:43111`. */
+  readonly url: string
+  readonly token: string
+  /** Defaults to the global `fetch`; tests and unusual transports inject their own. */
+  readonly fetch?: (input: string, init?: RequestInit) => Promise<Response>
+}
+
+export class BridgeError extends Error {
+  constructor(message: string, readonly status: number) { super(message) }
+}
+
+const messageOf = async (response: Response): Promise<string> => {
+  const text = await response.text().catch(() => "")
+  try {
+    const body = JSON.parse(text) as { message?: unknown; error?: unknown }
+    if (typeof body.message === "string") return body.message
+    if (typeof body.error === "string") return body.error
+  } catch { /* not JSON */ }
+  return text.slice(0, 300) || `HTTP ${response.status}`
+}
+
+export class BridgeClient {
+  readonly #base: string
+  readonly #fetch: (input: string, init?: RequestInit) => Promise<Response>
+  readonly #token: string
+  constructor(options: BridgeOptions) {
+    this.#base = options.url.replace(/\/+$/, "")
+    this.#token = options.token
+    this.#fetch = options.fetch ?? ((input, init) => fetch(input, init))
+  }
+
+  async #request(path: string, init: RequestInit = {}): Promise<Response> {
+    const response = await this.#fetch(`${this.#base}${path}`, { ...init, headers: { ...(init.headers as Record<string, string> | undefined), authorization: `Bearer ${this.#token}`, ...(init.body ? { "content-type": "application/json" } : {}) } })
+    if (response.status === 401) throw new BridgeError("CADCAMFUN refused the token (401). Use the token the running application was launched with.", 401)
+    return response
+  }
+
+  async tools(): Promise<ReadonlyArray<BridgeTool>> {
+    const response = await this.#request("/api/ai/actions")
+    if (!response.ok) throw new BridgeError(`Could not read the CADCAMFUN catalogue: ${await messageOf(response)}`, response.status)
+    return ((await response.json()) as { tools: ReadonlyArray<BridgeTool> }).tools
+  }
+
+  /** Runs one action. A refusal by the application (400) is returned as `{ ok: false, error }`, so the agent can read it and recover. */
+  async invoke(projectId: string, tool: string, input: Record<string, unknown>, signal?: AbortSignal): Promise<unknown> {
+    const response = await this.#request("/api/ai/actions/invoke", { method: "POST", body: JSON.stringify({ projectId, tool, input }), ...(signal ? { signal } : {}) })
+    if (response.status === 400) return { ok: false, error: await messageOf(response) }
+    if (!response.ok) throw new BridgeError(`CADCAMFUN could not run ${tool}: ${await messageOf(response)}`, response.status)
+    return ((await response.json()) as { result: unknown }).result
+  }
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+/**
+ * `@cadcamfunv2/cadcamfun-nikcli-plugin` (RM-11, spec 27 §4.4): the application's CAD/CAM action catalogue as tools of a standalone nikcli.
+ *
+ * Install it in nikcli's config next to a running CADCAMFUN:
+ *
+ *   { "plugin": [["file:///path/to/packages/nikcli-plugin/src/index.ts", { "url": "http://127.0.0.1:PORT", "token": "...", "projectId": "..." }]] }
+ *
+ * (or `CADCAMFUN_URL`, `CADCAMFUN_TOKEN`, `CADCAMFUN_PROJECT` in the environment). nikcli then has the same tool ids as the in-app
+ * assistant (`cad`, `cad_edit`, `cam`, `cam_edit`, `library`, `memory`, `research`, `vcs`, `vcs_edit`, ...), each carrying its
+ * actions behind `action`, with the application's own descriptions. The list is read from the running application, so the plugin
+ * never carries a second copy of the catalogue: a new action there is a new action here.
+ *
+ * What it will not do, by design: delete or replace work (the application asks a person first; an outside client has no such
+ * prompt) and delegate to the specialist agents (those run inside the application).
+ */
+import { BridgeClient, type BridgeOptions, type BridgeTool } from "./client.ts"
+import { toolShape, type Zod } from "./schema.ts"
+
+export { BridgeClient, BridgeError, type BridgeTool } from "./client.ts"
+export { toZod, toolShape } from "./schema.ts"
+
+/** nikcli's `tool()` helper and the zod it validates with (`@nikcli-ai/plugin/tool`); injected so nikcli's own copy is used. */
+export interface ToolFactory {
+  (input: { description: string; args: Record<string, unknown>; execute: (args: any, context: any) => Promise<unknown> }): unknown
+  schema: Zod
+}
+
+export interface CadcamPluginOptions extends BridgeOptions {
+  /** The project the tools act on, unless a call names another with `projectId`. */
+  readonly projectId?: string
+}
+
+const textOf = (value: unknown): string => typeof value === "string" ? value : JSON.stringify(value) ?? "null"
+
+/** One nikcli tool per catalogue tool of the running application. */
+export const createCadcamTools = async (options: CadcamPluginOptions & { readonly tool: ToolFactory }): Promise<Record<string, unknown>> => {
+  const client = new BridgeClient(options)
+  const z = options.tool.schema
+  const tools: ReadonlyArray<BridgeTool> = await client.tools()
+  return Object.fromEntries(tools.map((entry) => {
+    const { shape, summary } = toolShape(entry.parameters, z)
+    const refused = entry.actions.filter((action) => action.kind === "destructive").map((action) => action.name)
+    const description = [
+      entry.description.trim(),
+      summary ? `\nActions (required fields): ${summary}.` : "",
+      refused.length > 0 ? `\nNot available from outside the application (they need a person's approval there): ${refused.join(", ")}.` : "",
+      "\nThis tool runs in the open CADCAMFUN project; pass projectId to act on another."
+    ].join("")
+    return [entry.id, options.tool({
+      description,
+      args: { ...shape, projectId: z.string().optional().describe("The CADCAMFUN project id; defaults to the plugin's project") },
+      execute: async (args: Record<string, unknown>, context: { abort?: AbortSignal }) => {
+        const { projectId: named, ...input } = args
+        const projectId = typeof named === "string" && named !== "" ? named : options.projectId
+        if (!projectId) return JSON.stringify({ ok: false, error: "No CADCAMFUN project: set the plugin's projectId option (or CADCAMFUN_PROJECT) or pass projectId." })
+        try { return textOf(await client.invoke(projectId, entry.id, input, context?.abort)) }
+        catch (cause) { return JSON.stringify({ ok: false, error: cause instanceof Error ? cause.message : String(cause) }) }
+      }
+    })]
+  }))
+}
+
+const fromEnvironment = (options: Record<string, unknown> = {}): CadcamPluginOptions => {
+  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ?? {}
+  const url = String(options["url"] ?? env["CADCAMFUN_URL"] ?? "")
+  const token = String(options["token"] ?? env["CADCAMFUN_TOKEN"] ?? "")
+  if (!url || !token) throw new Error("@cadcamfunv2/cadcamfun-nikcli-plugin needs the running application's url and token (plugin options, or CADCAMFUN_URL and CADCAMFUN_TOKEN).")
+  const projectId = options["projectId"] ?? env["CADCAMFUN_PROJECT"]
+  return { url, token, ...(typeof projectId === "string" && projectId !== "" ? { projectId } : {}) }
+}
+
+/** The nikcli server plugin: `{ tool }` hook with the catalogue's tools. */
+export const CadcamPlugin = async (_input: unknown, options?: Record<string, unknown>): Promise<{ tool: Record<string, unknown> }> => {
+  // The configuration is checked first, so a missing url or token is reported as that and not as a missing SDK.
+  const configuration = fromEnvironment(options)
+  // nikcli supplies the SDK; a variable specifier keeps this package free of a dependency on it (and of its types).
+  const specifier = "@nikcli-ai/plugin/tool"
+  const { tool } = (await import(specifier)) as { tool: unknown }
+  return { tool: await createCadcamTools({ ...configuration, tool: tool as unknown as ToolFactory }) }
+}
+
+export default { id: "cadcamfun", server: CadcamPlugin }

package/src/schema.ts

@@ -0,0 +1,95 @@
+/**
+ * JSON Schema -> zod, for the subset the catalogue's tool schemas use (`z.toJSONSchema` output: objects, arrays, enums, consts,
+ * unions, primitives, local `$ref`s). The zod namespace is injected: nikcli validates tool arguments with its own copy of zod, and
+ * a schema built with another copy is not one it can read.
+ *
+ * A tool's arguments are a union over its actions, discriminated by `action`. nikcli wants an object shape, so `toolShape`
+ * flattens the union: `action` is the enum of the actions and every other field of any action is optional. That is a hint for
+ * the model, not the validation: CADCAMFUN validates each call against the action's own schema and answers a refusal as a result.
+ */
+export type Json = { readonly [key: string]: unknown }
+/** The part of zod's API used here; `any` because the namespace is the caller's copy. */
+export type Zod = any
+
+const isRecord = (value: unknown): value is Json => typeof value === "object" && value !== null && !Array.isArray(value)
+
+export const toZod = (schema: unknown, z: Zod, defs: Json = {}, depth = 0): any => {
+  if (!isRecord(schema) || depth > 12) return z.any()
+  const root = isRecord(schema["$defs"]) ? { ...defs, ...schema["$defs"] } : defs
+  const describe = (type: any) => typeof schema["description"] === "string" ? type.describe(schema["description"]) : type
+  const ref = schema["$ref"]
+  if (typeof ref === "string") {
+    const target = root[ref.replace(/^#\/\$defs\//, "")]
+    return target === undefined ? z.any() : toZod(target, z, root, depth + 1)
+  }
+  if ("const" in schema) return describe(z.literal(schema["const"] as never))
+  if (Array.isArray(schema["enum"])) {
+    const values = schema["enum"] as unknown[]
+    if (values.length > 0 && values.every((value) => typeof value === "string")) return describe(z.enum(values as [string, ...string[]]))
+    return describe(z.union(values.map((value) => z.literal(value as never)) as never))
+  }
+  const variants = (schema["anyOf"] ?? schema["oneOf"]) as unknown
+  if (Array.isArray(variants)) {
+    const members = variants.map((member) => toZod(member, z, root, depth + 1))
+    return describe(members.length === 1 ? members[0] : members.length === 0 ? z.any() : z.union(members))
+  }
+  const type = schema["type"]
+  if (Array.isArray(type)) return describe(z.union(type.map((t) => toZod({ ...schema, type: t }, z, root, depth + 1))))
+  switch (type) {
+    case "string": return describe(z.string())
+    case "number": return describe(z.number())
+    case "integer": return describe(z.number().int())
+    case "boolean": return describe(z.boolean())
+    case "null": return describe(z.null())
+    case "array": return describe(z.array(toZod(schema["items"], z, root, depth + 1)))
+    case "object": {
+      const properties = isRecord(schema["properties"]) ? schema["properties"] : {}
+      const required = new Set(Array.isArray(schema["required"]) ? (schema["required"] as string[]) : [])
+      if (Object.keys(properties).length === 0 && isRecord(schema["additionalProperties"])) return describe(z.record(z.string(), toZod(schema["additionalProperties"], z, root, depth + 1)))
+      const shape = Object.fromEntries(Object.entries(properties).map(([key, value]) => {
+        const member = toZod(value, z, root, depth + 1)
+        return [key, required.has(key) ? member : member.optional()]
+      }))
+      return describe(z.object(shape).passthrough ? z.object(shape).passthrough() : z.object(shape))
+    }
+    default: return z.any()
+  }
+}
+
+export interface ToolShape {
+  /** The args object nikcli's `tool()` takes. */
+  readonly shape: Record<string, any>
+  readonly actions: ReadonlyArray<string>
+  /** `action: field, field` for each action, to append to the tool's description. */
+  readonly summary: string
+}
+
+/** Flattens a tool's per-action union into one object shape (see the module note). */
+export const toolShape = (parameters: unknown, z: Zod): ToolShape => {
+  const root = isRecord(parameters) ? parameters : {}
+  const defs = isRecord(root["$defs"]) ? root["$defs"] : {}
+  const variants = (Array.isArray(root["anyOf"]) ? root["anyOf"] : Array.isArray(root["oneOf"]) ? root["oneOf"] : [root]).filter(isRecord)
+  const actions: string[] = []
+  const fields = new Map<string, Array<{ readonly schema: unknown; readonly required: boolean }>>()
+  const summary: string[] = []
+  for (const variant of variants) {
+    const properties = isRecord(variant["properties"]) ? variant["properties"] : {}
+    const required = new Set(Array.isArray(variant["required"]) ? (variant["required"] as string[]) : [])
+    const action = isRecord(properties["action"]) ? properties["action"] : undefined
+    const names = action === undefined ? [] : "const" in action ? [String(action["const"])] : Array.isArray(action["enum"]) ? (action["enum"] as unknown[]).map(String) : []
+    actions.push(...names)
+    const needs = [...required].filter((key) => key !== "action")
+    for (const name of names) summary.push(`${name}${needs.length > 0 ? ` (${needs.join(", ")})` : ""}`)
+    for (const [key, schema] of Object.entries(properties)) {
+      if (key === "action") continue
+      fields.set(key, [...(fields.get(key) ?? []), { schema, required: required.has(key) }])
+    }
+  }
+  const shape: Record<string, any> = {}
+  if (actions.length > 0) shape["action"] = z.enum([...new Set(actions)] as [string, ...string[]]).describe("Which action of the tool to run")
+  for (const [key, uses] of fields) {
+    const distinct = new Set(uses.map((use) => JSON.stringify(use.schema)))
+    shape[key] = (distinct.size === 1 ? toZod(uses[0]!.schema, z, defs) : z.any()).optional()
+  }
+  return { shape, actions: [...new Set(actions)], summary: summary.join("; ") }
+}