@fargowealth/fargo-ai-cli 1.4.2 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 1.5.0 — 2026-10-15
+
+- Align the Portal and Fargo Pass displayed CLI version with this package.
+- Discover the selected employee business directory by Chinese name, group and aliases; load background dictionaries only through the selected business's dependencies.
+
+- Return a two-part Markdown confirmation (overall parameters + item rows) from
+  expense preview. Require explicit caller attestation of human confirmation
+  plus the unchanged preview pin before execution. Add schema-backed display
+  templates for expense, travel reimbursement and external payment; those display
+  templates do not enable unreviewed submission branches.
+
+- Reuse one online Fargo identity within an expense tool task. Concurrent reads
+  share the result; local credential changes, logout and task expiry invalidate it.
+  Revalidate online before a mutation, and discard the context on completion.
+- Permit a fresh independent expense after matching prior attempts are confirmed
+  terminated by detail read-back. Preserve active/completed duplicate blocking and
+  durable one-shot journals; never add a business association or erase old receipts.
+
+- Share one own-HR response and one checked definition per expense preparation;
+  schedule 13 live lookups by schema dependencies with a concurrency limit of four.
+  Keep identity/admission and pre-write schema checks; never cache bank/rate values
+  across operations. Add a versioned execution contract to the expense bundle.
+- Use decimal half-up currency multiplication, reject impossible invoice dates,
+  and verify persisted rates, accounting items and attachment names/sizes as well
+  as amounts and file UUIDs. Document pending/unknown/duplicate recovery outcomes.
+
+- Add the local `yida_submit_expense` adapter for the reviewed ordinary,
+  non-project expense form: own HR bank details, live company/accounting/rate
+  lookups, uploaded PDF receipt, pinned preview, invoice/order duplicate checks,
+  durable one-shot submission and read-back. Generic form submission stays disabled.
+- Add one local `yida_cancel_request` MCP tool shared across declared process
+  businesses: preview and version pinning, own-originator/form/process checks,
+  one-shot termination, durable duplicate protection and API read-back. Keep
+  completed/ordinary forms blocked and ambiguous results out of automatic retries.
+- Capture calculation, option-loading, linkage, visibility, dataset-query and
+  script-reference metadata in YiDA model v2; retain legacy model support.
+- Add the local read-only `yida_resolve_field` tool and reviewed self/department
+  initialization adapters. Preserve the originating form context and reject
+  write functions, raw MCP expressions and unrelated HR fields.
+- Verify one explicitly authorized 0.06 HKD synthetic payment via API, with
+  recorded duplicate protection and exact amount/currency/attachment readback.
+
+- Add local personal YiDA OAuth, account-isolated credential profiles, refresh
+  and logout commands, and read-only schema modeling.
+- Add `yida_connection_status` and `yida_describe_form` to the local MCP bridge;
+  keep YiDA authorization and execution on the client computer.
+- Include OpenYida attribution and its MIT license for adapted protocol and
+  schema conventions.
+- Add local business catalog/package commands and MCP tools backed by the
+  LEGO publisher, atomic paired schema/handbook cache, immutable workflow pins,
+  enterprise isolation, integrity/version checks and live schema drift detection.
+
 ## 1.4.2
 
 - Add generic large-file upload to Media and R2 resources with resumable TUS and optional local FFmpeg compression.

package/README.md

@@ -37,7 +37,8 @@ reused by both MCP and local CLI operations.
   deploy composition, and migration-file ordering.
 - CLI has no generic R2 or Cloudflare administration commands.
 - `fargo mcp serve` is the local stdio bridge for WorkBuddy, Claude Code,
-  Codex, and Cursor.
+  Codex, and Cursor. It executes the reserved `yida_*` tools locally and
+  forwards other tools to hosted Fargo Pass.
 - `fargo mcp tools` and `fargo mcp call` support scripts and one-shot
   diagnostics without starting an MCP host.
 
@@ -47,6 +48,140 @@ fargo mcp call lego_app_read --args '{"action":"get","appId":"app_xxx"}'
 fargo mcp call lego_app_read --args-file ./arguments.json
 ```
 
+## Personal YiDA connection
+
+YiDA runs in the local CLI for client Agents. Sign in to Fargo first, then
+authorize your own DingTalk/YiDA account:
+
+```sh
+fargo yida auth login --endpoint https://xdlonl.aliwork.com --corp-id ding376dac86ffe9d2dbf2c783f7214b6d69
+fargo yida auth status
+fargo yida schema APP_GITLRTH76PM6J4M29F5D FORM-0AE7D3E4C01D45AC97D8C68DF7FF6B6CH3LQ
+```
+
+Login uses the OpenYida-compatible public client, `openid corpid`, an ephemeral
+IPv4 loopback callback at `/oauth/callback`, and the YiDA service's token
+exchange. It requires that the target YiDA environment accept this client
+and callback. The OAuth screen identifies the provider as YiDA. This is
+YiDA's personal Bearer-token channel, distinct from the DingTalk server API
+`x-acs-dingtalk-access-token` / `systemToken` channel.
+
+Each operation verifies the current Fargo identity with `ping_who_am_i`.
+YiDA credentials stay in owner-restricted local files under `~/.fargo/yida`
+(`%APPDATA%/Fargo AI/yida` on Windows), isolated by Fargo issuer, account and
+organization, then by YiDA enterprise and member. They are not sent to Fargo
+servers or printed in CLI/MCP output. State checks, a refresh lock, and identity
+checks protect callback handling and rotating tokens. These are restricted
+files, not an OS keychain or encrypted credential vault.
+
+`auth status` and `auth profiles` report local metadata only. If multiple
+profiles exist, select the exact returned `profile` ID with `--profile` for
+schema reads and logout. Logout attempts provider revocation and always removes
+the selected local credentials; `remoteRevoked` reports whether the provider
+confirmed success. `fargo auth logout` alone does not revoke YiDA credentials.
+
+The client MCP connection adds five read-only tools and two workflow write tools:
+
+| Tool | Result |
+| --- | --- |
+| `yida_connection_status` | Current Fargo account's local YiDA profiles; no tokens |
+| `yida_describe_form` | Field IDs, labels, aliases, parent fields, static options, detected source/association references and event bindings |
+| `yida_resolve_field` | Live options or linked defaults from a reviewed read-only expression and its originating form |
+| `yida_business_list` | Admitted business packages matching the selected local enterprise |
+| `yida_business_bundle` | Versioned Schema and Handbook, cached as one package and checked against the live YiDA schema |
+| `yida_cancel_request` | Preview, then terminate the current member's own running process; requires a declared business capability and final YiDA permission |
+| `yida_submit_expense` | Preview, then submit the current member's own ordinary non-project expense using one reviewed form adapter, live HR/bank/default/rate lookups, a registered PDF upload receipt and invoice/order duplicate checks |
+
+```sh
+fargo mcp call yida_describe_form --args '{"appType":"APP_GITLRTH76PM6J4M29F5D","formUuid":"FORM-0AE7D3E4C01D45AC97D8C68DF7FF6B6CH3LQ"}'
+fargo yida auth logout --profile <profileId>
+```
+
+The LEGO publisher is App `app_5c7114fa1a53`; the App is published
+for company-account access without a marketplace listing. These commands require
+CLI 1.5.0 or later:
+
+```sh
+fargo yida business list
+fargo yida business get external_payment
+```
+
+`business list` returns catalog summaries (Chinese name, business ID, version
+and capability flags), not all Schema/Handbook bodies. Agents should match the
+user's request against this directory, ask the user to choose when ambiguous,
+and fetch only the selected business. There is no keyword/search flag yet.
+The YiDA publisher selects 14 homepage business entries, grouped as finance,
+business, assets and other applications, with Chinese display names and aliases.
+Enterprise matching does not prove personal permission to submit, and catalog
+presence does not enable an unimplemented submission adapter. Department,
+currency, exchange-rate, accounting, company and supplier sources are business
+dependencies, not standalone employee entries. Query only a selected business's
+configured fields with `yida_resolve_field`; adapters resolve the applicant and
+department through that form's reviewed personal connector. Copied/test forms
+and retired HR workflows do not appear in the employee directory.
+
+Each fetch checks App access online, validates the enterprise, package hash and
+minimum CLI version, then caches the pair atomically under `~/.fargo/yida-business`
+(`%APPDATA%/Fargo AI/yida-business` on Windows). Cache keys include the verified
+Fargo account/organization, publisher App and YiDA profile. Cache hits still
+check authorization; network and permission errors have no offline fallback.
+The returned `pin` contains `businessId`, `revision` and `bundleHash`; pass all
+three to `yida_business_bundle` for subsequent calls within the same workflow.
+The CLI equivalent is `business get <businessId> --revision <n> --bundle-hash <hash>`.
+An unpinned lookup checks the latest release; a pinned lookup retains its exact
+version. Published revisions are immutable and latest-version downgrades fail.
+
+Every package lookup also reads the live YiDA schema. `status=schema_changed`
+requires model and handbook review before a new business revision is published.
+No package currently enables generic submission. Dynamic dictionary values are
+queried at runtime, rather than cached in the handbook. All admitted
+App users use one default role; YiDA data access still follows personal grants.
+See [publisher maintenance](../../apps/yida-connector/README.md) for release steps.
+
+All 45 captured process businesses declare the same cancellation capability;
+42 receipt tables do not. `yida_cancel_request` defaults to a read-only preview.
+Pass its `pin.revision`, `pin.bundleHash` and `previewHash` back with `dryRun:false`
+only when the user requests cancellation. Execution verifies live schema and
+form/process binding, enterprise/member and originator, current state and unchanged
+preview; YiDA still decides whether the member can terminate. This retains the
+record and does not reverse completed downstream business effects. Already
+terminated/canceled returns `already_cancelled`; completed requests are blocked.
+Active termination has mock coverage, but has not yet been tested on a live active
+instance. A preview and no-op read of the user's manually terminated test do not
+prove active-write permission. Accepted or ambiguous writes are never resent;
+only proven pre-dispatch failures and authorization rejections permit a later
+explicit attempt after a fresh preview. Journals live under `~/.fargo/yida-operations`
+(Windows: `%APPDATA%/Fargo AI/yida-operations`). These tools require this updated
+CLI 1.5.0 or later.
+
+The expense adapter supports only ordinary expense form
+`FORM-6EB2E57A94CF4445BB28508DC45262E3MDDX` at its reviewed live schema hash.
+It does not accept raw form payloads, an alternative originator, projects or other
+forms. Its payment company follows the member's configured default and its payment
+currency/rates follow live definitions; `amount` and `currency` are the original
+expense. Bank fields come only from the member's own HR record. Pass a local JSON
+receipt from the registered YiDA PDF upload as `attachmentReceiptPath`. Preview
+first, then pass `dryRun:false`, `previewHash`, `revision` and `bundleHash` to execute.
+One invoice gets one durable operation record; an ambiguous write must be reconciled
+instead of retried. This local reviewed adapter is separate from the still-disabled
+generic submission capability in business packages.
+
+Schema reads use the user's permission to read YiDA design schemas. Dynamic
+options and effective employee permissions need runtime verification; formula
+and event detection does not reconstruct all business logic. Model output omits
+default values and executable source, reports traversal/option truncation, and
+does not submit or modify any business record. Only public-cloud HTTPS
+`aliwork.com` / `yidaapps.com` origins are supported in this first version.
+
+Restart the client MCP process after updating the CLI to discover the new tools.
+Hosted-only MCP connections do not expose these local tools. For an unpublished
+checkout, use `node packages/fargo-cli/bin/fargo.mjs` in place of `fargo`.
+
+Implementation references and the upstream MIT notice are included in
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+
+Run the local connector and CLI tests with `npm test` from this package.
+
 ## Large-file transfer
 
 `fargo upload` transfers a local file using an upload descriptor supplied by
@@ -250,3 +385,70 @@ serialized across CLI processes.
 
 Never copy, upload, commit, or print the credential file. Use
 `fargo auth logout` when a device is no longer trusted.
+
+## YiDA runtime rules
+
+The local `yida_describe_form` response now includes `runtime.rules` with the
+configured calculation expressions, dependent fields, lookup source fields,
+conditions and triggers. Page JavaScript is not executed. Distributed business
+packages carry configuration-read and runtime-verification states separately.
+
+Use the local MCP tool `yida_resolve_field` with `appType`, `formUuid`, `fieldId`,
+`kind` (`options` or `linked_value`), the dependent field `values`, and an exact
+`profile` when needed. The tool re-reads the actual schema and uses its configured
+read-only lookup expression with the originating form context. It rejects raw
+expressions, unsupported functions and cross-app queries. No arbitrary POST or
+general submission tool is exposed. A related-option response reaching 100 items
+is possibly truncated and must not be treated as a complete dictionary.
+
+The reviewed payment initialization adapter queries only the token member's HR
+record, filters the returned fields, validates department membership, and resolves
+the first department manager according to the page implementation. It does not
+return unrelated HR fields or accept another user's identity.
+
+`docs/yida/process-center/README.md` indexes every captured page and its paired
+Schema/Handbook; the LEGO App distributes the 87 process/receipt business packages.
+The local source implements these capabilities; this CLI update is not yet
+published to npm. The specifically authorized 0.06 HKD payment smoke test is
+recorded separately and does not enable general submission.
+
+The reviewed expense execution contract lives in `schema.execution` of the ordinary
+expense business package. It records semantic inputs, source rules and dependencies,
+rounding, currencies, upload/read-back representation, and recovery states. Its
+13 lookups run by dependency with at most four concurrent queries; a single own-HR
+response supplies applicant and bank fields within each preparation. No live values
+are cached between preview and execution. Currency multiplication uses decimal
+half-up cents; the API read-back checks rates, accounting categories and file metadata.
+
+Update the contract source in `src/yida-expense-contract.mjs`, materialize it with
+`node scripts/yida-update-expense-contract.mjs` from the repository root, then freeze
+a new immutable Schema/Handbook revision. The capture script reapplies this contract
+only for the exact reviewed schema hash. Publishing a business package does not
+update the local CLI executable. See `docs/yida/expense-workflow-review.md` for the
+measured request count, remaining upload/recovery gaps and validation limits.
+
+Expense identity checks now share an internal task context for one MCP invocation
+(preparation or execution), not the lifetime of a chat or the MCP process. It is
+never an externally supplied identity or persistent permission cache. Reads share
+one online result while local credential changes invalidate the task; execution
+performs an additional online check immediately before writing. Contexts expire
+within five minutes and are closed on success or failure. Credential rotation
+requires a fresh task, including same-account token refresh during the task.
+
+A matching prior expense may be excluded from duplicate blocking only after its
+details confirm the same owner/form/process and TERMINATED/CANCELED state. A fresh
+application has no business linkage to the terminated one. The local replay guard
+uses the verified terminal history to distinguish a new attempt without deleting
+or bypassing the earlier operation journal. Active/completed/uncertain records
+continue to block duplicates; no mutation is automatically retried.
+
+### User confirmation before expense submission
+
+The three main business Handbooks contain their own overall-parameter and detail-row
+Markdown tables. `yida_submit_expense` returns the rendered table in
+`confirmation.markdown`; show both parts to the user and wait for an explicit
+Confirm of that exact preview. Only then pass `userConfirmed: true` with
+`dryRun: false`, `revision`, `bundleHash`, and `previewHash`. A change to data,
+attachments or the preview requires a fresh user confirmation. This Boolean is
+caller attestation, not independent proof of a human signature. Travel and external
+payment display templates do not enable new submission adapters.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,28 @@
+# OpenYida
+
+The YiDA OAuth/token protocol, schema conventions and endpoint usage in
+`src/yida-auth.mjs` and `src/yida-schema.mjs` are adapted from OpenYida:
+https://github.com/openyida/openyida
+Revision: bdd45f54605cc7239ff8db116b2ef1b506179c70
+
+MIT License
+
+Copyright (c) 2026 Alibaba Group Holding Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fargowealth/fargo-ai-cli",
-  "version": "1.4.2",
-  "description": "Agent-neutral Fargo AI CLI, MCP client, and LEGO project tooling",
+  "version": "1.5.0",
+  "description": "Fargo Pass CLI and local MCP with personal YiDA authorization, business definitions and confirmed expense requests",
   "type": "module",
   "bin": {
     "fargo": "bin/fargo.mjs",
@@ -11,11 +11,15 @@
     "bin",
     "src",
     "CHANGELOG.md",
+    "THIRD_PARTY_NOTICES.md",
     "README.md"
   ],
   "engines": {
     "node": ">=20.19.0"
   },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
   "dependencies": {
     "fflate": "^0.8.2",
     "ignore": "^7.0.6"

package/src/cli.mjs

@@ -10,12 +10,17 @@ import { callMcpTool, listMcpTools } from "./mcp-client.mjs";
 import { runMcpProxy } from "./mcp-proxy.mjs";
 import { installAgentMcp } from "./agent-install.mjs";
 import { transferUpload } from "./upload-transfer.mjs";
+import { runYidaCli } from "./yida-cli.mjs";
 
 export async function runCli(args, options = {}) {
   const stdout = options.stdout ?? process.stdout;
   const stderr = options.stderr ?? process.stderr;
   const store = options.store ?? createCredentialStore(options.storeOptions);
   try {
+    if (args[0] === "yida") {
+      await runYidaCli(args.slice(1), store, { ...options, stdout, stderr });
+      return;
+    }
     if (isHelpOption(args) && args[0] === "lego" && args[1] === "deploy") {
       stdout.write(LEGO_DEPLOY_HELP);
       return;
@@ -150,7 +155,7 @@ export async function runCli(args, options = {}) {
       await installAgentConnection(args, "workbuddy", stdout, store, options);
       return;
     }
-    throw new Error("Usage: fargo auth login|device|status|logout | fargo agent install --agent <agent> | fargo mcp serve|tools|call | fargo upload | fargo lego snapshot upload|list|download | fargo lego deploy | fargo lego d1 migrate plan|apply | fargo workbuddy install | fargo version");
+    throw new Error("Usage: fargo auth login|device|status|logout | fargo yida auth|schema|business | fargo agent install --agent <agent> | fargo mcp serve|tools|call | fargo upload | fargo lego snapshot upload|list|download | fargo lego deploy | fargo lego d1 migrate plan|apply | fargo workbuddy install | fargo version");
   } catch (error) {
     stderr.write(`fargo: ${error instanceof Error ? error.message : "unknown error"}\n`);
     if (options.throwOnError) throw error;
@@ -162,6 +167,7 @@ const ROOT_HELP = `Usage: fargo <command> [options]
 
 Commands:
   auth login|device|status|logout
+  yida auth login|status|profiles|logout | schema <appType> <formUuid>
   agent install --agent <codex|claude-code|cursor|workbuddy>
   mcp serve|tools|call
   upload --file <path> --request-file <path>

package/src/constants.mjs

@@ -1,4 +1,4 @@
-export const CLI_VERSION = "1.4.2";
+export const CLI_VERSION = "1.5.0";
 export const DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
 export const DEFAULT_AUTH_URL = "https://auth.fargowealth.app";
 export const DEFAULT_API_URL = "https://mcp.fargowealth.app";

package/src/loopback-receiver.mjs

@@ -4,7 +4,8 @@ import { createServer } from "node:http";
 const LOOPBACK_HOST = "127.0.0.1";
 
 export async function createLoopbackReceiver(options = {}) {
-  const callbackPath = `/oauth/callback/${(options.randomBytes ?? randomBytes)(18).toString("base64url")}`;
+  const callbackPath = options.callbackPath ?? `/oauth/callback/${(options.randomBytes ?? randomBytes)(18).toString("base64url")}`;
+  if (!/^\/oauth\/callback(?:\/[A-Za-z0-9_-]+)?$/.test(callbackPath)) throw new Error("Invalid OAuth loopback callback path");
   const timeoutMs = Math.max(1_000, Number(options.timeoutMs) || 10 * 60 * 1_000);
   let address;
   let settled = false;

package/src/mcp-client.mjs

@@ -1,12 +1,14 @@
 import { DEFAULT_MCP_URL } from "./constants.mjs";
 import { authenticatedRequest, responsePayload } from "./api-client.mjs";
+import { callLocalYidaTool, isLocalYidaTool, localYidaTools } from "./yida-tools.mjs";
 
 export async function listMcpTools(store, options = {}) {
   const result = await mcpRequest(store, "tools/list", {}, options);
-  return result;
+  return { ...result, tools: [...(result.tools ?? []).filter(tool => !isLocalYidaTool(tool.name)), ...localYidaTools()] };
 }
 
 export async function callMcpTool(store, name, args, options = {}) {
+  if (isLocalYidaTool(name)) return callLocalYidaTool(store, name, args, options);
   return mcpRequest(store, "tools/call", { name, arguments: args }, options);
 }
 

package/src/mcp-proxy.mjs

@@ -1,6 +1,7 @@
 import { createInterface } from "node:readline";
 import { CLI_VERSION, DEFAULT_MCP_URL } from "./constants.mjs";
 import { currentCredential, refreshCurrentCredential } from "./auth.mjs";
+import { callLocalYidaTool, isLocalYidaTool, localYidaTools } from "./yida-tools.mjs";
 
 export async function runMcpProxy(store, options = {}) {
   const input = options.input ?? process.stdin;
@@ -17,8 +18,21 @@ export async function runMcpProxy(store, options = {}) {
       try { message = JSON.parse(line); }
       catch { return; }
       try {
+        if (message.method === "tools/call" && isLocalYidaTool(message.params?.name)) {
+          if (message.id === undefined) return;
+          let result;
+          try { result = await callLocalYidaTool(store, message.params.name, message.params.arguments, options); }
+          catch (error) { result = { isError: true, content: [{ type: "text", text: error instanceof Error ? error.message : "Local YiDA tool failed" }] }; }
+          output.write(`${JSON.stringify({ jsonrpc: "2.0", id: message.id, result })}\n`);
+          return;
+        }
         const responses = await forward(message, false);
-        for (const response of responses) output.write(`${JSON.stringify(response)}\n`);
+        for (const response of responses) {
+          if (message.method === "tools/list" && !message.params?.cursor && response.id === message.id && Array.isArray(response.result?.tools)) {
+            response.result.tools = [...response.result.tools.filter(tool => !isLocalYidaTool(tool.name)), ...localYidaTools()];
+          }
+          output.write(`${JSON.stringify(response)}\n`);
+        }
       } catch (error) {
         if (message.id !== undefined) output.write(`${JSON.stringify({ jsonrpc: "2.0", id: message.id, error: { code: -32001, message: error instanceof Error ? error.message : "Fargo MCP proxy failed" } })}\n`);
       }