@pancake-pos/app-cli 2026.1.5 → 2026.1.7

package/README.md

@@ -4,10 +4,13 @@ The `pos-app` command for Pancake POS apps: `login`, `dev`, `check`, `build`, `d
 
 ```bash
 npx @pancake-pos/app-cli login --shop 123 --token <token>   # from POS › Settings › Advanced › Custom apps › Connect CLI
-npx pos-app dev
-npx pos-app deploy
+npm run dev      # in an app created by create-pos-app (scripts call pos-app)
+npm run deploy
+npx @pancake-pos/app-cli versions   # any command, from anywhere
 ```
 
+Do not run `npx pos-app`: the `pos-app` package on npm is not published by Pancake, and npx downloads it outside an installed project.
+
 Docs: https://pos.pages.fm/developers/apps/en (English), https://pos.pages.fm/developers/apps (Tiếng Việt). For AI tools: https://pos.pages.fm/developers/apps/llms-full.txt.
 
 Part of Pancake POS Apps. Use is limited to building apps for Pancake POS.

package/dist/cli.js

@@ -16,7 +16,7 @@ var __export = (target, all) => {
 
 // src/api.ts
 async function apiRequest(credentials, method, path, body) {
-  if (!credentials.token) throw new ApiError(401, "Ch\u01B0a \u0111\u0103ng nh\u1EADp: ch\u1EA1y `pos-app login` tr\u01B0\u1EDBc");
+  if (!credentials.token) throw new ApiError(401, 'Ch\u01B0a \u0111\u0103ng nh\u1EADp: ch\u1EA1y l\u1EC7nh \u1EDF n\xFAt "K\u1EBFt n\u1ED1i CLI" tr\xEAn trang \u1EE8ng d\u1EE5ng tu\u1EF3 bi\u1EBFn c\u1EE7a POS (npx @pancake-pos/app-cli login \u2026)');
   const headers = { Authorization: `Bearer ${credentials.token}`, Accept: "application/json" };
   let payload;
   if (body instanceof FormData) payload = body;
@@ -635,10 +635,10 @@ function createSiteHandler(options) {
     res.writeHead(status, all);
     res.end(req.method === "HEAD" ? void 0 : buffer);
   };
-  const serve = async (req, res, kind, path, body, site, cache2) => {
+  const serve = async (req, res, kind, path, body, site, cache3) => {
     if (!body) return false;
     const headers = headersFor(kind, path, site.policy);
-    send(req, res, 200, cache2 ? { ...headers, "Cache-Control": cache2 } : headers, body);
+    send(req, res, 200, cache3 ? { ...headers, "Cache-Control": cache3 } : headers, body);
     return true;
   };
   return async (req, res) => {
@@ -837,18 +837,18 @@ var init_server = __esm({
     init_site();
     MAX_DEV_ERRORS = 500;
     clip = (value, max) => typeof value === "string" ? value.slice(0, max) : void 0;
-    readBody = (req, max) => new Promise((resolve3) => {
+    readBody = (req, max) => new Promise((resolve4) => {
       let size = 0;
       const chunks = [];
       req.on("data", (chunk) => {
         size += chunk.length;
         if (size > max) {
-          resolve3(null);
+          resolve4(null);
           req.destroy();
         } else chunks.push(chunk);
       });
-      req.on("end", () => resolve3(Buffer.concat(chunks).toString("utf8")));
-      req.on("error", () => resolve3(null));
+      req.on("end", () => resolve4(Buffer.concat(chunks).toString("utf8")));
+      req.on("error", () => resolve4(null));
     });
     LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
   }
@@ -1017,7 +1017,7 @@ async function startDev(options) {
     versions: { dev: outDir },
     activeVersion: "dev",
     posOrigins: options.posOrigins,
-    apiOrigins: [new URL(options.api).origin],
+    apiOrigins: [.../* @__PURE__ */ new Set([new URL(options.api).origin, ...POS_API_ORIGINS])],
     allowedOrigins: readManifest(root).network?.allowed_origins ?? [],
     dev: true,
     devEvents: events,
@@ -1050,11 +1050,11 @@ async function startDev(options) {
     await modules.dispose();
   };
   try {
-    await new Promise((resolve3, reject) => {
+    await new Promise((resolve4, reject) => {
       server.once("error", reject);
       server.listen(options.port, "127.0.0.1", () => {
         server.off("error", reject);
-        resolve3();
+        resolve4();
       });
     });
   } catch (error2) {
@@ -1069,11 +1069,11 @@ async function startDev(options) {
     buildErrors: () => buildErrors,
     async close() {
       await stopWatching();
-      await new Promise((resolve3) => server.close(() => resolve3()));
+      await new Promise((resolve4) => server.close(() => resolve4()));
     }
   };
 }
-var DEFAULT_POS_ORIGINS;
+var DEFAULT_POS_ORIGINS, POS_API_ORIGINS;
 var init_dev = __esm({
   "src/dev.ts"() {
     "use strict";
@@ -1092,6 +1092,19 @@ var init_dev = __esm({
       "https://crm.pancake.in",
       "https://crm.pancake.biz"
     ];
+    POS_API_ORIGINS = [
+      "https://pos.pancake.vn",
+      "https://pos.pancake.ph",
+      "https://pos.pancake.id",
+      "https://pos.pancake.in",
+      "https://pos.pancake.biz",
+      "https://pos.pages.fm",
+      "https://crm.pancake.ph",
+      "https://crm.pancake.id",
+      "https://crm.pancake.in",
+      "https://crm.pancake.biz",
+      "https://dev.pos.pancake.vn"
+    ];
   }
 });
 
@@ -1147,7 +1160,7 @@ var CLI_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    CLI_VERSION = true ? "2026.1.5" : JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+    CLI_VERSION = true ? "2026.1.7" : JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
   }
 });
 
@@ -1227,7 +1240,7 @@ function createMcpServer(options) {
         const task = run2().finally(() => pending.delete(task));
         pending.add(task);
       });
-      return new Promise((resolve3) => lines.on("close", () => void Promise.all(pending).then(() => resolve3())));
+      return new Promise((resolve4) => lines.on("close", () => void Promise.all(pending).then(() => resolve4())));
     }
   };
 }
@@ -1398,20 +1411,343 @@ var init_records = __esm({
   }
 });
 
-// src/mcp/docs.ts
+// src/mcp/api.ts
 import { existsSync as existsSync5, readFileSync as readFileSync4 } from "node:fs";
 import { dirname as dirname4, join as join7 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-function docsFile() {
+function apiFile() {
   let dir = dirname4(fileURLToPath2(import.meta.url));
   for (let i = 0; i < 4; i += 1) {
-    const file = join7(dir, "docs", "llms-full.txt");
+    const file = join7(dir, "docs", "openapi.json");
     if (existsSync5(file)) return file;
     dir = dirname4(dir);
   }
   return null;
 }
-function loadSections(text = readFileSync4(docsFile() ?? "", "utf8")) {
+function loadApi(spec) {
+  if (!spec && cache) return cache;
+  const source = spec ?? JSON.parse(readFileSync4(apiFile() ?? "", "utf8"));
+  const operations = [];
+  for (const [path, item] of Object.entries(source.paths ?? {})) {
+    for (const method of METHODS2) {
+      const op = item[method];
+      if (op) operations.push({ method: method.toUpperCase(), path, tag: op.tags?.[0] ?? "", summary: op.summary ?? "", op });
+    }
+  }
+  const api = { spec: source, operations };
+  if (!spec) cache = api;
+  return api;
+}
+function routeKey(path) {
+  let value = path.trim().replace(/^https?:\/\/[^/]+/, "").replace(/[?#].*$/, "");
+  value = value.replace(/\$\{[^}]*\}/g, "{}").replace(/\{[^}]*\}/g, "{}").replace(/(^|\/):[A-Za-z_]\w*/g, "$1{}");
+  value = value.replace(/^\/?api\/v1(?=\/)/, "");
+  if (!value.startsWith("/")) value = `/${value}`;
+  return value.replace(/\/+$/, "") || "/";
+}
+function findOperations(path, method, api = loadApi()) {
+  const input = routeKey(path).split("/");
+  let best = -1;
+  let found = [];
+  for (const operation of api.operations) {
+    if (method && operation.method !== method.toUpperCase()) continue;
+    const segments = routeKey(operation.path).split("/");
+    if (segments.length !== input.length) continue;
+    let score = 0;
+    const ok2 = segments.every((segment, i) => {
+      if (segment === input[i]) return score += segment === "{}" ? 0 : 1, true;
+      return segment === "{}" && input[i] !== "";
+    });
+    if (!ok2) continue;
+    if (score > best) [best, found] = [score, [operation]];
+    else if (score === best) found.push(operation);
+  }
+  return found;
+}
+function searchApi(query, limit = 15, api = loadApi()) {
+  const terms = [...new Set(words(query))];
+  const method = terms.find((term) => METHODS2.includes(term))?.toUpperCase();
+  const keywords = terms.filter((term) => !METHODS2.includes(term));
+  if (!keywords.length) return [];
+  return api.operations.filter((operation) => !method || operation.method === method).map((operation) => {
+    const { op } = operation;
+    const fields = [
+      [`${operation.summary} ${Object.values(op["x-summary-i18n"] ?? {}).join(" ")}`, 4],
+      [`${operation.path.replace(/\{[^}]+\}/g, " ")} ${operation.path.replace(/[{}/_]/g, " ")}`, 3],
+      [`${(op.tags ?? []).join(" ")} ${JSON.stringify(op["x-tags-i18n"] ?? "")}`, 3],
+      [(op.parameters ?? []).map((param) => param.name ?? "").join(" "), 1],
+      [op.description ?? "", 1]
+    ];
+    const folded = fields.map(([text, weight]) => [new Set(words(text)), weight]);
+    let score = 0;
+    let matched = 0;
+    for (const term of keywords) {
+      let hit = 0;
+      for (const [set, weight] of folded) if ([...set].some((word) => word === term || term.length >= 4 && word.startsWith(term))) hit += weight;
+      if (hit) matched += 1;
+      score += hit;
+    }
+    return { operation, score: score * (matched / keywords.length) ** 2 };
+  }).filter((item) => item.score > 0).sort((a, b) => b.score - a.score).slice(0, limit).map((item) => item.operation);
+}
+function formatSearch(query, limit = 15, api = loadApi()) {
+  const hits = searchApi(query, limit, api);
+  if (hits.length) return hits.map((hit) => `${hit.method} ${hit.path}: ${hit.summary} [${hit.tag}]${needs(hit.method)}`).join("\n");
+  const groups = api.spec["x-tagGroups"] ?? [];
+  return [
+    `No endpoint matches "${query}". Try other English keywords (orders, customers, inventory, warehouses\u2026) or a path such as /shops/{SHOP_ID}/orders.`,
+    "Groups:",
+    ...groups.map((group) => `- ${group.name}: ${group.tags.join(", ")}`)
+  ].join("\n");
+}
+function resolve2(value, spec) {
+  let current = value;
+  for (let i = 0; i < 5 && current?.$ref; i += 1) {
+    const path = String(current.$ref).replace(/^#\//, "").split("/");
+    current = path.reduce((node, key) => node?.[key], spec);
+  }
+  return current;
+}
+function enumText(schema) {
+  const values = schema.enum.slice(0, MAX_ENUM).map((value) => JSON.stringify(value));
+  return `${values.join(" | ")}${schema.enum.length > MAX_ENUM ? ` | \u2026 (${schema.enum.length} values)` : ""}`;
+}
+function typeText(input, ctx, indent, depth, chain = []) {
+  if (!input) return "unknown";
+  if (input.$ref) {
+    const name = refName(input.$ref);
+    if (depth >= ctx.maxDepth - 1 || chain.includes(name)) {
+      ctx.refs.add(name);
+      return name;
+    }
+    return typeText(resolve2(input, ctx.spec), ctx, indent, depth, [...chain, name]);
+  }
+  const schema = input;
+  const union = schema.oneOf ?? schema.anyOf;
+  if (Array.isArray(union)) return union.map((item) => typeText(item, ctx, indent, depth, chain)).join(" | ");
+  if (Array.isArray(schema.allOf)) {
+    const merged = { type: "object", properties: {}, required: [] };
+    for (const part of schema.allOf.map((item) => resolve2(item, ctx.spec) ?? {})) {
+      Object.assign(merged.properties, part.properties ?? {});
+      merged.required.push(...part.required ?? []);
+    }
+    return typeText(merged, ctx, indent, depth, chain);
+  }
+  if (Array.isArray(schema.enum)) return enumText(schema);
+  const types = Array.isArray(schema.type) ? schema.type : [schema.type ?? (schema.properties ? "object" : schema.items ? "array" : "unknown")];
+  const nullable = types.includes("null") || schema.nullable ? " | null" : "";
+  const type = types.find((item) => item !== "null") ?? "unknown";
+  if (type === "array") {
+    const item = typeText(schema.items, ctx, indent, depth, chain);
+    return `${item.includes("\n") || item.includes("|") ? `Array<${item}>` : `${item}[]`}${nullable}`;
+  }
+  if (type === "object") {
+    const properties = Object.entries(schema.properties ?? {});
+    if (!properties.length) {
+      const extra = schema.additionalProperties && typeof schema.additionalProperties === "object" ? typeText(schema.additionalProperties, ctx, indent, depth + 1, chain) : "unknown";
+      return `Record<string, ${extra}>${nullable}`;
+    }
+    if (depth >= ctx.maxDepth) return `{ \u2026 }${nullable}`;
+    const required = new Set(schema.required ?? []);
+    const inner = `${indent}  `;
+    const lines = properties.map(([name, property]) => {
+      const key = /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);
+      const resolved = resolve2(property, ctx.spec) ?? {};
+      return `${inner}${key}${required.has(name) ? "" : "?"}: ${typeText(property, ctx, inner, depth + 1, chain)};${comment(property.description ?? resolved.description)}`;
+    });
+    return `{
+${lines.join("\n")}
+${indent}}${nullable}`;
+  }
+  const format = schema.format ? ` /* ${schema.format} */` : "";
+  return `${type === "integer" ? "number" : type}${format}${nullable}`;
+}
+function renderSchema(schema, spec) {
+  for (const maxDepth of [5, 4, 3, 2, 1]) {
+    const ctx = { spec, maxDepth, refs: /* @__PURE__ */ new Set() };
+    const text = typeText(schema, ctx, "", 0);
+    if (text.split("\n").length <= MAX_LINES || maxDepth === 1) return { text, refs: [...ctx.refs] };
+  }
+  return { text: "unknown", refs: [] };
+}
+function paramLine(param, spec) {
+  const schema = resolve2(param.schema, spec) ?? {};
+  const descriptions = schema["x-enum-descriptions"];
+  const { text } = renderSchema(Array.isArray(schema.enum) && descriptions?.length ? { ...schema, enum: void 0 } : schema, spec);
+  const parts = [text.includes("\n") ? "object" : text];
+  if (param.required) parts.push("required");
+  if (schema.default !== void 0) parts.push(`default ${JSON.stringify(schema.default)}`);
+  const values = Array.isArray(schema.enum) && descriptions?.length ? `; values: ${schema.enum.slice(0, MAX_ENUM).map((value, i) => `${JSON.stringify(value)} = ${descriptions[i] ?? ""}`).join(", ")}` : "";
+  const hint = param.in === "path" && ID_HINTS[param.name] ? `; use ${ID_HINTS[param.name]}` : "";
+  const description = String(param.description ?? schema.description ?? "").trim();
+  return `- ${param.name} (${parts.join(", ")})${description ? `: ${description}` : ""}${values}${hint}`;
+}
+function callSnippet(operation, query) {
+  const path = operation.path.replace(/\{([^}]+)\}/g, (_, name) => name === "SHOP_ID" ? "${pos.shop.id}" : `\${${camel(name)}}`).replace(/\/$/, "");
+  const required = query.filter((param) => param.required);
+  const options = required.length ? `, { query: { ${required.map((param) => `${JSON.stringify(param.name)}: \u2026`).join(", ")} } }` : "";
+  const method = operation.method.toLowerCase();
+  if (method === "get" || method === "delete") return `const response = await pos.api.${method}(\`${path}\`${options});`;
+  return `const response = await pos.api.${method}(\`${path}\`, body${options});`;
+}
+function example(content, spec) {
+  if (!content) return null;
+  let value = content.example;
+  if (value === void 0 && content.examples) {
+    const first = Object.values(content.examples)[0];
+    value = (resolve2(first, spec) ?? first)?.value;
+  }
+  if (value === void 0) return null;
+  const text = JSON.stringify(value, null, 2);
+  return text.length > MAX_EXAMPLE ? `${text.slice(0, MAX_EXAMPLE)}
+\u2026 (truncated)` : text;
+}
+function describeField(operation, field, api = loadApi()) {
+  const { spec } = api;
+  const parts = field.split(".").filter(Boolean);
+  const inBody = parts[0] === "body" || parts[0] === "request";
+  const root = inBody ? bodyContent(operation.op, spec)?.[1] : responseContent(operation.op, spec)?.[1];
+  let node = resolve2(root?.schema, spec);
+  const walked = [];
+  for (const part of inBody ? parts.slice(1) : parts) {
+    while (node && (node.type === "array" || node.items)) node = resolve2(node.items, spec);
+    const next = node?.properties?.[part];
+    if (!next) {
+      const fields = Object.keys(node?.properties ?? {});
+      return `No field "${part}" under ${inBody ? "body" : "response"}${walked.length ? `.${walked.join(".")}` : ""} of ${operation.method} ${operation.path}.${fields.length ? ` Fields: ${fields.join(", ")}.` : ""}`;
+    }
+    walked.push(part);
+    node = resolve2(next, spec);
+  }
+  const rendered = renderSchema(node, spec);
+  return [
+    `# ${operation.method} ${operation.path} \u203A ${inBody ? "body" : "response"}${walked.length ? `.${walked.join(".")}` : ""}`,
+    ...node?.description ? [String(node.description)] : [],
+    "```ts",
+    rendered.text,
+    "```",
+    ...rendered.refs.length ? [`Shared schemas used above: ${rendered.refs.join(", ")}. Call get_api with schema to expand one.`] : []
+  ].join("\n");
+}
+function describeOperation(operation, api = loadApi()) {
+  const { spec } = api;
+  const { op } = operation;
+  const params = (op.parameters ?? []).map((param) => resolve2(param, spec) ?? param);
+  const byPlace = (place) => params.filter((param) => param.in === place);
+  const refs = /* @__PURE__ */ new Set();
+  const lines = [
+    `# ${operation.method} ${operation.path}`,
+    operation.summary,
+    ...op.description && op.description !== operation.summary ? [String(op.description).trim()] : [],
+    `Tag: ${operation.tag}`,
+    "",
+    "## Call from an app",
+    "```ts",
+    callSnippet(operation, byPlace("query")),
+    "```",
+    operation.method === "GET" ? "- App tokens may call it; GET needs nothing in access.methods." : `- App tokens may call it after the admin approves "${operation.method}" in access.methods of pos-app.json.`,
+    "- The signed-in user's POS permissions and the app's access limits still apply: handle 403 (and 429).",
+    "- pos.api.get/delete take { query }; post/put take the body, then { query }. pos.api adds the base URL (\u2026/api/v1) and the app token."
+  ];
+  for (const [title, place] of [
+    ["Path parameters", "path"],
+    ["Query parameters", "query"]
+  ]) {
+    const list2 = byPlace(place);
+    if (list2.length) lines.push("", `## ${title}`, ...list2.map((param) => paramLine(param, spec)));
+  }
+  let collapsed = false;
+  const body = bodyContent(op, spec);
+  if (body) {
+    const [type, content] = body;
+    const rendered = renderSchema(content.schema, spec);
+    rendered.refs.forEach((ref) => refs.add(ref));
+    collapsed ||= rendered.text.includes("{ \u2026 }");
+    lines.push("", `## Request body (${type}${content.required ? ", required" : ""})`, "```ts", rendered.text, "```");
+    const sample = example(content, spec);
+    if (sample) lines.push("Example:", "```json", sample, "```");
+  }
+  const response = responseContent(op, spec);
+  if (response) {
+    const [status, content] = response;
+    const rendered = renderSchema(content.schema, spec);
+    rendered.refs.forEach((ref) => refs.add(ref));
+    collapsed ||= rendered.text.includes("{ \u2026 }");
+    lines.push("", `## Response ${status}`, "```ts", rendered.text, "```");
+    const sample = example(content, spec);
+    if (sample) lines.push("Example:", "```json", sample, "```");
+  }
+  if (collapsed) lines.push("", 'Nested objects shown as { \u2026 }: call get_api again with field to expand one, for example "data.items" (response) or "body.customer" (request body).');
+  if (refs.size) lines.push("", `Shared schemas used above: ${[...refs].join(", ")}. Call get_api with schema to expand one.`);
+  return lines.join("\n");
+}
+function describeSchema(name, api = loadApi()) {
+  const schemas = api.spec.components?.schemas ?? {};
+  const key = Object.keys(schemas).find((item) => item.toLowerCase() === name.trim().toLowerCase());
+  if (!key) return null;
+  const rendered = renderSchema(schemas[key], api.spec);
+  const description = schemas[key].description ? `
+${schemas[key].description}` : "";
+  const refs = rendered.refs.filter((ref) => ref !== key);
+  return [`# ${key}${description}`, "```ts", rendered.text, "```", ...refs.length ? [`Shared schemas used above: ${refs.join(", ")}.`] : []].join("\n");
+}
+var METHODS2, MAX_LINES, MAX_ENUM, MAX_EXAMPLE, ID_HINTS, cache, fold, words, needs, refName, comment, camel, bodyContent, responseContent, schemaNames;
+var init_api2 = __esm({
+  "src/mcp/api.ts"() {
+    "use strict";
+    METHODS2 = ["get", "post", "put", "delete", "patch"];
+    MAX_LINES = 160;
+    MAX_ENUM = 30;
+    MAX_EXAMPLE = 2500;
+    ID_HINTS = {
+      SHOP_ID: "pos.shop.id",
+      ORDER_ID: "the order system_id (record.system_id in pos.data)",
+      CUSTOMER_ID: "the customer id (record.id in customer.* targets, draft.customer_id in order targets)",
+      PRODUCT_ID: "the product id (record.id in product targets)",
+      PURCHASE_ID: "the purchase id (record.id in purchase targets)",
+      EXPORT_ID: "the export id (record.id in export targets)",
+      TRANSFER_ID: "the transfer id (record.id in warehouse_transfer targets)",
+      VARIATION_ID: "a variation id (variation_id of draft items)",
+      WAREHOUSE_ID: "a warehouse id (warehouse_id in pos.data, or list_shop_meta)"
+    };
+    cache = null;
+    fold = (text) => text.toLowerCase().normalize("NFD").replace(/[\u0300-\u036f]/g, "").replace(/đ/g, "d");
+    words = (text) => fold(text).split(/[^a-z0-9_]+/).filter((word) => word.length >= 2);
+    needs = (method) => method === "GET" ? "" : ` (needs "${method}" in access.methods)`;
+    refName = (ref) => ref.split("/").pop() ?? ref;
+    comment = (text) => {
+      const value = String(text ?? "").replace(/\s+/g, " ").trim();
+      return value ? ` // ${value.length > 120 ? `${value.slice(0, 117)}\u2026` : value}` : "";
+    };
+    camel = (name) => name.toLowerCase().replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+    bodyContent = (op, spec) => {
+      const body = op.requestBody && (resolve2(op.requestBody, spec) ?? op.requestBody);
+      const entry = body?.content && Object.entries(body.content)[0];
+      return entry ? [entry[0], { ...entry[1], required: body.required }] : null;
+    };
+    responseContent = (op, spec) => {
+      const [status, response] = Object.entries(op.responses ?? {}).find(([code]) => code.startsWith("2")) ?? [];
+      const content = response && (resolve2(response, spec) ?? response).content?.["application/json"];
+      return status && content ? [status, content] : null;
+    };
+    schemaNames = (api = loadApi()) => Object.keys(api.spec.components?.schemas ?? {});
+  }
+});
+
+// src/mcp/docs.ts
+import { existsSync as existsSync6, readFileSync as readFileSync5 } from "node:fs";
+import { dirname as dirname5, join as join8 } from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+function docsFile() {
+  let dir = dirname5(fileURLToPath3(import.meta.url));
+  for (let i = 0; i < 4; i += 1) {
+    const file = join8(dir, "docs", "llms-full.txt");
+    if (existsSync6(file)) return file;
+    dir = dirname5(dir);
+  }
+  return null;
+}
+function loadSections(text = readFileSync5(docsFile() ?? "", "utf8")) {
   const sections2 = [];
   for (const block of text.split(/^Source: /m).slice(1)) {
     const newline = block.indexOf("\n");
@@ -1440,8 +1776,8 @@ function loadSections(text = readFileSync4(docsFile() ?? "", "utf8")) {
   return sections2;
 }
 function sections() {
-  cache ??= docsFile() ? loadSections() : [];
-  return cache;
+  cache2 ??= docsFile() ? loadSections() : [];
+  return cache2;
 }
 function searchDocs(query, limit = 5, all = sections()) {
   const terms = [...new Set(tokenize(query))];
@@ -1466,7 +1802,7 @@ function typeBlock(name, all) {
   }
   return null;
 }
-function example(target, location, resource) {
+function example2(target, location, resource) {
   const id = target.replace(/[^a-z0-9]+/g, "-").replace(/-+$/, "").slice(0, 40);
   if (target === "nav.item") return '```json\n{ "target": "nav.item", "id": "nav", "label": "Reconciliation", "page": "home" }\n```';
   if (target === "app.page") return '```json\n{ "target": "app.page", "id": "home", "title": "Reconciliation", "render": "iframe", "entry": "page/index.html" }\n```';
@@ -1534,19 +1870,19 @@ function describeTarget(target, all = sections()) {
     ...types.length ? ["", "```ts", ...types, "```"] : [],
     "",
     "## Example",
-    example(target, location, resource),
+    example2(target, location, resource),
     ...docs.map((section) => `
 ## Docs: ${section.heading}
 ${section.text.replace(/^#+ .+\n/, "")}`)
   ].join("\n");
 }
-var API_VERSION, cache, tokenize, DATA, MANIFEST, pascal;
+var API_VERSION, cache2, tokenize, DATA, MANIFEST, pascal;
 var init_docs = __esm({
   "src/mcp/docs.ts"() {
     "use strict";
     init_manifest();
     API_VERSION = "2026-01";
-    cache = null;
+    cache2 = null;
     tokenize = (text) => text.toLowerCase().match(/[a-z0-9_.\-*]{2,}/g) ?? [];
     DATA = {
       "details.action": "DetailsData",
@@ -1589,7 +1925,7 @@ function createTools(ctx) {
   let dev = null;
   const devLog = [];
   const shop = () => {
-    if (!ctx.shop) throw new Error("Missing shop: start the server with --shop <shop_id> or run pos-app login --shop <shop_id>");
+    if (!ctx.shop) throw new Error("Missing shop: start the server with --shop <shop_id> or run npx @pancake-pos/app-cli login --shop <shop_id>");
     return ctx.shop;
   };
   const get = (path) => apiRequest(ctx.credentials, "GET", `/shops/${shop()}/${path}`);
@@ -1645,6 +1981,52 @@ ${hit.text.slice(0, 4e3)}`).join("\n\n---\n\n") };
         return text ? { text } : fail(`Unknown target. Valid targets: ${targets(API_VERSION2).join(", ")}`);
       }
     },
+    {
+      name: "search_api",
+      title: "Search the Open API",
+      description: 'Find Open API endpoints to call with pos.api. Lists only the operations published in the Open API, the only ones app tokens may call. Keywords in English or Vietnamese, optionally with a method ("post order"). Returns method, path, summary, tag and the access.methods it needs; then call get_api for the details.',
+      inputSchema: { type: "object", properties: { query: { type: "string", description: 'For example "order list", "update customer", "inventory by warehouse"' }, limit: { type: "integer", minimum: 1, maximum: 30 } }, required: ["query"] },
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      async run(args) {
+        return { text: formatSearch(String(args.query ?? ""), Math.min(Number(args.limit) || 15, 30)) };
+      }
+    },
+    {
+      name: "get_api",
+      title: "Describe an Open API endpoint",
+      description: 'How to call one Open API endpoint from an app: the pos.api call, the access.methods it needs, path and query parameters, request body and response shapes (TypeScript-like) and an example. path as in the docs (/shops/{SHOP_ID}/orders/{ORDER_ID}) or as called (/shops/123/orders/45). field expands one nested object ("data.items" in the response, "body.customer" in the request body). schema describes a shared schema such as Order or Customer instead.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          method: { type: "string", enum: ["GET", "POST", "PUT", "DELETE"] },
+          path: { type: "string", description: "For example /shops/{SHOP_ID}/orders/{ORDER_ID}" },
+          field: { type: "string", description: "Dotted field path to expand, for example data.items or body.customer" },
+          schema: { type: "string", description: "Shared schema name, for example Order" }
+        }
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      async run(args) {
+        if (args.schema !== void 0) {
+          const text = describeSchema(String(args.schema));
+          return text ? { text } : fail(`Unknown schema. Shared schemas: ${schemaNames().join(", ")}`);
+        }
+        const path = String(args.path ?? "").trim();
+        if (!path) return fail("Pass path (for example /shops/{SHOP_ID}/orders) or schema. Use search_api to find endpoints.");
+        const method = args.method === void 0 ? void 0 : String(args.method).toUpperCase();
+        const found = findOperations(path, method);
+        if (!found.length) {
+          const other = method ? findOperations(path) : [];
+          if (other.length) return fail(`${method} ${path} is not in the Open API. Methods for this path: ${other.map((item) => item.method).join(", ")}.`);
+          return fail(`${path} is not in the Open API, so app tokens cannot call it. Use search_api to find a published endpoint.`);
+        }
+        if (found.length > 1 && new Set(found.map((item) => item.method)).size > 1) {
+          return { text: `Several operations match; pass method:
+${found.map((item) => `- ${item.method} ${item.path}: ${item.summary}`).join("\n")}` };
+        }
+        const operation = found[0];
+        return { text: args.field ? describeField(operation, String(args.field)) : describeOperation(operation) };
+      }
+    },
     {
       name: "list_shop_meta",
       title: "List shop metadata",
@@ -1854,6 +2236,7 @@ var init_tools = __esm({
     init_dev();
     init_manifest();
     init_version();
+    init_api2();
     init_docs();
     API_VERSION2 = "2026-01";
     ORDER_STATUSES = [
@@ -1921,13 +2304,14 @@ var init_mcp = __esm({
     init_tools();
     INSTRUCTIONS = `Tools for building a Pancake POS app in this folder.
 Typical loop: get_target and search_docs to pick targets and types; list_shop_meta and sample_context to use real ids and fields;
+search_api and get_api before every pos.api call (only Open API endpoints work, with their exact parameters and response shapes);
 write code, then check_app until there are no errors; dev_start and try it in POS, then get_errors; deploy (uploads an inactive version for an admin to activate).
 When the user wants to report a POS Apps bug or ask for a feature, draft it, show it, and call send_feedback only after they confirm.`;
   }
 });
 
 // src/cli.ts
-import { resolve as resolve2 } from "node:path";
+import { resolve as resolve3 } from "node:path";
 function parseArgs(argv) {
   const [command = "help", ...rest] = argv;
   const flags = {};
@@ -1945,7 +2329,7 @@ function parseArgs(argv) {
 async function run(argv, io = defaultIo) {
   const { command, flags } = parseArgs(argv);
   const json2 = flags.json === true;
-  const root = resolve2(str2(flags.cwd) ?? process.cwd());
+  const root = resolve3(str2(flags.cwd) ?? process.cwd());
   const emit = (result, text) => io.out(json2 ? JSON.stringify(result) : text);
   const line = (mark, e) => `${mark} ${e.path ? `${e.path}: ` : ""}${e.message}${e.code && e.code !== "error" ? ` [${e.code}]` : ""}`;
   const fail2 = (errors, warnings = []) => {
@@ -1967,7 +2351,7 @@ async function run(argv, io = defaultIo) {
     const credentials = readCredentials();
     const shopOf = () => {
       const shop = str2(flags.shop) ?? credentials.shop;
-      if (!shop) throw new Error("Thi\u1EBFu --shop <shop_id> (ho\u1EB7c l\u01B0u b\u1EB1ng `pos-app login --shop`)");
+      if (!shop) throw new Error("Thi\u1EBFu --shop <shop_id> (ho\u1EB7c l\u01B0u b\u1EB1ng `npx @pancake-pos/app-cli login --shop`)");
       return shop;
     };
     switch (command) {
@@ -1996,7 +2380,7 @@ async function run(argv, io = defaultIo) {
         return 0;
       }
       case "build": {
-        const result = await buildApp(root, { outDir: resolve2(root, str2(flags.out) ?? "dist") });
+        const result = await buildApp(root, { outDir: resolve3(root, str2(flags.out) ?? "dist") });
         emit({ ok: true, outDir: result.outDir, files: result.files, totalBytes: result.totalBytes }, `\u2714 Build xong ${Object.keys(result.files).length} file (${(result.totalBytes / 1024).toFixed(0)} KB) \u2192 ${result.outDir}`);
         return 0;
       }
@@ -2004,7 +2388,7 @@ async function run(argv, io = defaultIo) {
         const shop = shopOf();
         const code = await lint();
         if (code.errors.length) return fail2(code.errors, json2 ? code.warnings : []);
-        const result = await buildApp(root, { outDir: resolve2(root, "dist") });
+        const result = await buildApp(root, { outDir: resolve3(root, "dist") });
         const form = new FormData();
         form.append("bundle", new Blob([Buffer.from(zipDir(result.outDir))], { type: "application/zip" }), "bundle.zip");
         form.append("source", str2(flags.source) === "mcp" ? "mcp" : "cli");