@uipath/functions-tool 1.0.0

package/README.md

@@ -0,0 +1,179 @@
+# @uipath/functions-tool
+
+UiPath CLI plugin for JS/TS and Python Functions. Installed as a tool in the `uip` CLI.
+
+## How it works
+
+This package is a thin passthrough plugin. It does not contain build logic — it detects the project language and delegates every command to the appropriate language-specific CLI:
+
+- **JS/TS projects** → `cliRunner(args)` from `@uipath/coded-functions-js-cli` — bundled into `dist/tool.js`, called in-process
+- **Python projects** → `uipath <args>` (resolved from the codedagents-tool cache or PATH)
+
+### Architecture
+
+```
+Studio Web publish (JS/TS)
+  → FunctionsTool.buildAsync()        ← packager-tool-functions (browser packager)
+    → buildFunctionsPackage()         ← shared library in @uipath/coded-functions-js-packager
+
+Studio Web publish (Python)           ← TODO: not yet implemented
+  → FunctionsTool.buildAsync()        ← returns error; Python Functions team to implement
+                                         (see feat/functions-packager-wrapper)
+
+CLI: uip functions pack (JS/TS)
+  → cliRunner(["pack"])               ← @uipath/coded-functions-js-cli (bundled into dist/tool.js)
+    → buildFunctionsPackage()         ← same shared library, called in-process
+
+CLI: uip functions pack (Python)
+  → uipath pack                       ← Python CLI subprocess, entirely separate
+```
+
+### Call chain
+
+```
+uip functions <verb>
+  cli.ts:buildProgram()
+    discoverTools() → loads dist/tool.js via dynamic import
+    program.command("functions") → registerCommands(sub-program)
+      "setup" (hidden) → registerSetupCommand (runs natively, JS/TS only)
+                         verifies Node ≥20 + tsx; does NOT install uipath-functions
+      anything else    → command:* handler → runPassthrough(args)
+                           init/new: ensureSetup() first (Node ≥20 + tsx, idempotent)
+                           detectLanguage(cwd)
+                             uipath.json functions map → JS or Python
+                             fallback: package.json → JS, pyproject.toml → Python
+                             unknown (fresh dir) → peek --language flag, default JS
+                           JS/TS  → cliRunner(args) from bundled @uipath/coded-functions-js-cli  ← in-process
+                           Python → spawn(uipath, args, { stdio: "inherit" })
+                                    process.exit(child exit code)
+```
+
+### Language detection
+
+| Signal | Result |
+|---|---|
+| `uipath.json` functions map extension `.ts`/`.js` | javascript |
+| `uipath.json` functions map extension `.py` | python |
+| `package.json` present | javascript (fallback) |
+| `pyproject.toml` present | python (fallback) |
+| Neither (fresh directory) | peek `--language` arg; default javascript |
+
+## Commands
+
+| Command | JS/TS → `uipath-functions` (in-process) | Python → `uipath` (spawn) |
+|---|---|---|
+| `uip functions new` | `new --name <n> [--empty]` — scaffold project | `uipath new <n> --type function` — scaffold in-place |
+| `uip functions init` | ❌ not supported — use `new --empty` | `uipath init` — discover entrypoints, write entry-points.json etc. |
+| `uip functions serve` | `serve` — hot-reload server | _(no equivalent — use `run`)_ |
+| `uip functions run <name>` | `run <name>` — call local HTTP server | `uipath run <entrypoint>` — execute directly |
+| `uip functions pack` | `pack` | `uipath pack` |
+| `uip functions publish` | `publish` | `uipath publish` |
+| `uip functions push` | `push` — sync to Studio Web | `uipath push` — sync to Studio Web |
+
+> **Why `init` is Python-only:** Python's `pack` and `push` are dumb readers — they require
+> `entry-points.json` / `bindings.json` / `project.uiproj` to already exist and will hard-fail
+> otherwise. `uipath init` does the code introspection step that generates these files.
+> JS/TS `pack` and `push` introspect inline via `tsx`, so no separate init step is needed.
+
+> **Arg translation for Python:** `--language`/`-l` is dropped before forwarding (Python CLI has no such flag).
+> `--name <n>` is converted to a positional argument (`uipath new <n>`).
+
+> **`uip functions setup`** is hidden from help. JS/TS-only — verifies Node.js ≥20 and tsx.
+> Called automatically before `new` is forwarded. Callable manually for repair: `uip functions setup [--force]`
+
+## Typical workflow
+
+```sh
+# ── JS/TS project ────────────────────────────────────────────────────────────
+uip functions new --name my-fn --language ts   # scaffold + hello world; npm install runs automatically
+uip functions new --name my-fn --empty         # scaffold empty project (no sample function)
+cd my-fn
+uip functions serve                            # hot-reload server on :7070
+uip functions run hello --input '{"x":1}'     # invoke against local server
+uip functions push                             # sync to Studio Web
+uip functions pack && uip functions publish    # deploy to Orchestrator
+
+# ── Python project ───────────────────────────────────────────────────────────
+# Prereq: uipath CLI installed (pip install uipath)
+
+uip functions new --name my-fn --language py   # scaffold in current directory + sample function
+uip functions init                             # introspect code → entry-points.json, bindings.json, project.uiproj
+                                               # (required before pack/push; re-run whenever function signatures change)
+uip functions run main '{"message":"hi"}'      # run function directly (no server needed)
+uip functions push                             # sync to Studio Web
+uip functions pack && uip functions publish    # deploy to Orchestrator
+
+# ── After first command, --language is never needed again ────────────────────
+# uipath.json is created with .ts/.py entries; detectLanguage reads it automatically
+uip functions pack
+uip functions publish
+uip functions push
+```
+
+## Options
+
+### `uip functions new`
+| Flag | Description | Applies to |
+|---|---|---|
+| `--name <name>` | Project name / directory (default: `my-functions`) | JS/TS |
+| `--language <lang>` | `ts` (default), `js`, `py`, or `python` | both |
+| `--empty` | Skip hello world — create an empty project | JS/TS |
+
+> `--language` is a router flag consumed by `functions-tool`. It is never forwarded to either CLI.
+> `--name` is forwarded to `uipath-functions` as `--name <n>` (JS/TS) or as a positional arg to `uipath new <n>` (Python).
+> `--empty` is forwarded to `uipath-functions new --empty`. Has no effect for Python (Python `new` does not support it).
+
+### `uip functions init` _(Python only)_
+
+No flags — forwards directly to `uipath init`. For JS/TS projects this command exits with an error and suggests `uip functions new --empty`.
+
+### `uip functions serve`  _(JS/TS only)_
+| Flag | Description |
+|---|---|
+| `--runtime <runtime>` | `node` (default) or `deno` |
+| `--port <port>` | Port to listen on (default: `7070`) |
+
+### `uip functions run <name>`
+| Flag | Description | Applies to |
+|---|---|---|
+| `--port <port>` | Port the local server is on (default: `7070`) | JS/TS |
+| `--input <json>` | JSON input payload (default: `{}`) | JS/TS |
+| positional `<input>` | JSON input string | Python (`uipath run <entrypoint> '<json>'`) |
+
+### `uip functions pack`
+| Flag | Description | Applies to |
+|---|---|---|
+| `--nolock` | Exclude lock file from the package | JS/TS |
+
+### `uip functions publish`
+| Flag | Description | Applies to |
+|---|---|---|
+| `--url <url>` | UiPath platform URL (or `UIPATH_URL` env) | JS/TS |
+| `--org <org>` | Organization name (or `UIPATH_ORGANIZATION_NAME` env) | JS/TS |
+| `--tenant <tenant>` | Tenant name (or `UIPATH_TENANT_NAME` env) | JS/TS |
+| `--token <token>` | Access token (or `UIPATH_ACCESS_TOKEN` env) | JS/TS |
+| `--feed-id <id>` | Feed ID — skips the interactive picker (CI use) | JS/TS |
+
+> For Python, credentials are managed by the `uipath` Python CLI independently (via its own auth flow). The `--url/--org/--tenant/--token` flags are not forwarded to Python; run `uipath auth login` before using push/publish with Python projects.
+
+### `uip functions push`
+| Flag | Description | Applies to |
+|---|---|---|
+| `--url <url>` | UiPath platform URL (or `UIPATH_URL` env) | JS/TS |
+| `--project-id <id>` | Studio Web project ID — mandatory (or `UIPATH_PROJECT_ID` env) | JS/TS |
+| `--org <org>` | Organization name (or `UIPATH_ORGANIZATION_NAME` env) | JS/TS |
+| `--tenant <tenant>` | Tenant name (or `UIPATH_TENANT_NAME` env) | JS/TS |
+| `--token <token>` | Access token (or `UIPATH_ACCESS_TOKEN` env) | JS/TS |
+
+> For Python, credentials are managed by the `uipath` Python CLI independently — the `--url/--org/--tenant/--token/--project-id` flags are not forwarded. Run `uipath auth login` before using push with Python projects.
+
+## Known issues
+
+- **`uip functions new --language py` scaffolds an agent instead of a function** when `uipath-langchain` is installed. Tracked in [uipath-python#1543](https://github.com/UiPath/uipath-python/issues/1543).
+
+## Cache files
+
+| File | Contents |
+|---|---|
+| `~/.uipcli/.functions-tool-cache.json` | Cached Node.js path + version (written by `ensureSetup`) |
+| `~/.uipcli/.codedagents-tool-cache.json` | Read to resolve Python `uipath` binary path |