pterm 0.0.23 → 0.0.25

package/README.md

@@ -10,6 +10,8 @@ npm install -g pterm
 
 # Usage
 
+This README documents the stable public CLI surface.
+
 ## version
 
 prints the current version
@@ -20,10 +22,10 @@ prints the current version
 pterm version <type>
 ```
 
-- `type`: may be `terminal`, `pinokiod`, or `pinokio`
+- `type`: may be `terminal`, `pinokiod`, `pinokio`, or `script`
   - `terminal`: returns the pterm version
   - `pinokiod`: returns the pinokiod version
-  - `pinokio`: returns the pinokio version
+  - `pinokio`: returns the Pinokio app wrapper version
   - `script`: returns the valid script version for the current client. used for including in `pinokio.js`
 
 ### example
@@ -32,16 +34,88 @@ pterm version <type>
 pterm version terminal
 ```
 
+## refs
+
+Pinokio resource references use this syntax:
+
+```
+pinokio://<host>:<port>/<scope>/<id>
+```
+
+Examples:
+
+```
+pinokio://127.0.0.1:42000/api/cropper.git
+pinokio://192.168.86.26:42000/api/facefusion-pinokio.git
+```
+
+Currently documented scope:
+
+- `api`: an installed Pinokio app under `PINOKIO_HOME/api`
+
+How refs are used:
+
+- the `host:port` in a ref identifies the target Pinokio control plane, not the app's `ready_url`
+- `pterm` does not connect directly to the app endpoint described by the ref
+- `pterm` talks to the local Pinokio control plane, and the local control plane resolves or forwards the ref to the target Pinokio node as needed
+
+## open
+
+Open a URL on the local Pinokio node or on a connected peer node.
+
+### syntax
+
+```
+pterm open <url> [--peer <peer>] [--surface browser|popup] [--preset center-small|center-medium|center-large|fullscreen]
+```
+
+- `--peer`: optional target Pinokio node. May be a peer host, `host:port`, or peer name.
+- `--surface`: optional UI surface. `popup` requests a Pinokio popup window. `browser` forces the system browser. Default is popup-preferred.
+- `--preset`: optional popup size preset. Only applies when popup is used.
+
+Behavior:
+
+- `pterm` still talks to the local Pinokio control plane first
+- if `--peer` is set, the local node forwards the open request to that peer
+- if `--peer` is set, the URL is opened from that peer node's point of view, so `http://127.0.0.1:7860` means the peer's loopback
+- by default, `pterm open` prefers a Pinokio popup window
+- on a full Pinokio desktop node, the default opens a desktop popup
+- on a server-only or minimal node, the default automatically falls back to opening the system browser
+- default popup preset is `center-medium`
+- `center-medium` opens centered on the active display using roughly 64% of screen width and 72% of screen height, with minimum size `900x700`
+
+### examples
+
+Open a URL locally with the default popup-preferred behavior:
+
+```
+pterm open http://127.0.0.1:7860
+```
+
+Force the system browser instead of the default popup-preferred behavior:
+
+```
+pterm open http://127.0.0.1:7860 --surface browser
+```
+
+Open a URL on a peer node:
+
+```
+pterm open http://127.0.0.1:7860 --peer 192.168.86.26
+```
+
 ## start
 
-Start a pinokio script. Arguments can be passed into the script
+Start a pinokio script. `pterm` options go before `--`. Script args go after `--`.
 
 ### syntax
 
 ```
-pterm start <script_path> [<arg1>, <arg2>, ...]
+pterm start <script_path> [--ref <pinokio_ref>] [-- --<key>=<value> ...]
 ```
 
+With `--ref`, prefer relative script paths like `start.js`. `~/...` expansion is only local.
+
 ### examples
 
 Starting a script named `install.js`:
@@ -53,7 +127,7 @@ pterm start install.js
 Starting a script named `start.js` with parameters:
 
 ```
-pterm start start.js --port=3000 --model=google/gemma-3n-E4B-it
+pterm start start.js -- --port=3000 --model=google/gemma-3n-E4B-it
 ```
 
 Above command starts the script `start.js` with the following args:
@@ -65,6 +139,24 @@ Above command starts the script `start.js` with the following args:
 }
 ```
 
+Query parameters in the script path are also passed through as script input automatically:
+
+```
+pterm start 'run.js?mode=Default'
+```
+
+Starting a relative script inside a selected app:
+
+```
+pterm start start.js --ref pinokio://127.0.0.1:42000/api/metube-pinokio.git
+```
+
+Passing a script argument named `app` without conflicting with `pterm --ref`:
+
+```
+pterm start start.js --ref pinokio://127.0.0.1:42000/api/metube-pinokio.git -- --app=my-script-value
+```
+
 Which can be accessed in the `start.js` script, for example:
 
 ```json
@@ -90,8 +182,12 @@ Stops a script if running:
 
 ```
 pterm stop <script_path>
+pterm stop <script_path> --ref <pinokio_ref>
+pterm stop <pinokio_ref>
 ```
 
+With `--ref`, prefer relative script paths like `start.js`. `~/...` expansion is only local.
+
 
 ### example
 
@@ -101,6 +197,18 @@ Stop the `start.js` script if it's running:
 pterm stop start.js
 ```
 
+Stop a relative script inside a selected app:
+
+```
+pterm stop start.js --ref pinokio://127.0.0.1:42000/api/metube-pinokio.git
+```
+
+Stop all running scripts for an app:
+
+```
+pterm stop pinokio://127.0.0.1:42000/api/metube-pinokio.git
+```
+
 ## run
 
 Run a launcher. Equivalent to the user visiting a launcher page. By default it will run whichever script is the current launcher default. If the launcher exposes no explicit default, you can provide repeated `--default` selectors and Pinokio will match the first selector that exists in the launcher's current menu state.
@@ -109,6 +217,7 @@ Run a launcher. Equivalent to the user visiting a launcher page. By default it w
 
 ```
 pterm run <launcher_path_or_uri> [--default <selector>]... [--open]
+pterm run <pinokio_ref> [--default <selector>]... [--open]
 ```
 
 - `--open`: (optional) open URL results in the browser. Default behavior is to print the URL to stdout without opening a browser.
@@ -143,12 +252,57 @@ pterm run ~/pinokio/api/facefusion-pinokio.git \
   --default install.js
 ```
 
-Launch a script directly with query parameters. Query parameters are passed through as script input automatically.
+Run an installed app by Pinokio ref:
+
+```
+pterm run pinokio://192.168.86.26:42000/api/facefusion-pinokio.git \
+  --default 'run.js?mode=Default' \
+  --default run.js \
+  --default install.js
+```
+
+For direct script execution with query parameters, use `pterm start`. Query parameters are passed through as script input automatically.
 
 ```
 pterm start 'run.js?mode=Default'
 ```
 
+## download
+
+Clone an app repo into Pinokio's app directory without launching it.
+
+### syntax
+
+```
+pterm download <uri> [name] [--branch=<branch>]
+pterm download <uri> [name] -b <branch>
+```
+
+- `uri`: required git repository URI
+- `name`: (optional) target folder name under `PINOKIO_HOME/api`
+- `--branch` / `-b`: (optional) clone a specific branch
+
+Behavior:
+
+- if `name` is omitted, Pinokio uses the same default destination folder naming as `git clone <uri>`
+- if `name` is provided, Pinokio clones into `PINOKIO_HOME/api/<name>`
+- if the target folder already exists, the command fails with `already exists`
+- the command does not dedupe by repo URL
+
+### examples
+
+```
+pterm download https://github.com/example/my-launcher.git
+```
+
+```
+pterm download https://github.com/example/my-launcher.git my-launcher-dev
+```
+
+```
+pterm download https://github.com/example/my-launcher.git my-launcher-dev --branch=feature-x
+```
+
 ## search
 
 Search installed or available apps.
@@ -236,14 +390,37 @@ pterm which node
 pterm which git --json
 ```
 
+## home
+
+Get `PINOKIO_HOME`.
+
+### syntax
+
+```
+pterm home [--json]
+```
+
+- `--json`: (optional) print the raw JSON response instead of only the path.
+
+### examples
+
+```
+pterm home
+```
+
+```
+pterm home --json
+```
+
 ## status
 
-Get app status by app id.
+Get app status by app id or Pinokio ref.
 
 ### syntax
 
 ```
 pterm status <app_id> [--probe] [--timeout=<ms>]
+pterm status <pinokio_ref> [--probe] [--timeout=<ms>]
 ```
 
 - `--probe`: (optional) actively probe app health.
@@ -259,6 +436,10 @@ pterm status comfyanonymous-comfyui
 pterm status comfyanonymous-comfyui --probe --timeout=5000
 ```
 
+```
+pterm status pinokio://192.168.86.26:42000/api/comfyanonymous-comfyui --probe --timeout=5000
+```
+
 ## stars
 
 List starred apps.
@@ -314,12 +495,13 @@ pterm unstar comfyanonymous-comfyui
 
 ## logs
 
-Get app logs by app id.
+Get app logs by app id or Pinokio ref.
 
 ### syntax
 
 ```
 pterm logs <app_id> [--script=<name>] [--tail=<lines>]
+pterm logs <pinokio_ref> [--script=<name>] [--tail=<lines>]
 ```
 
 - `--script`: (optional) filter to a script.
@@ -335,11 +517,15 @@ pterm logs comfyanonymous-comfyui
 pterm logs comfyanonymous-comfyui --script=start --tail=200
 ```
 
+```
+pterm logs pinokio://192.168.86.26:42000/api/comfyanonymous-comfyui --script=start --tail=200
+```
+
 ## filepicker
 
 Display a file picker dialog, which lets the user select one or more file or folder paths, powered by tkinter.
 
-This API is NOT for uploading the actual files but for submitting file paths.
+This API is NOT for uploading the actual files but for submitting file paths. Use `pterm upload <pinokio_ref> <file...>` when a remote app needs real files staged onto its machine.
 
 ### syntax
 
@@ -372,12 +558,6 @@ The most basic command lets users select a single file:
 pterm filepicker
 ```
 
-which is equivalent to:
-
-```
-pterm filepicker --type=file
-```
-
 #### Select multiple files
 
 ```
@@ -402,6 +582,28 @@ pterm filepicker --filetype='images/*.png,*.jpg,*.jpeg'
 pterm filepicker --filetype='images/*.png,*.jpg,*.jpeg' --filetype='docs/*.pdf'
 ```
 
+## upload
+
+Stage one or more local files onto the selected app's machine and return remote filesystem paths that can be passed to path-based tasks.
+
+### syntax
+
+```
+pterm upload <app_id|pinokio_ref> <file...>
+```
+
+Quoted `~/...` file paths are expanded locally before upload.
+
+### examples
+
+```
+pterm upload facefusion-pinokio.git ./face.jpg ./video.mp4
+```
+
+```
+pterm upload pinokio://192.168.86.26:42000/api/facefusion-pinokio.git ./face.jpg ./video.mp4
+```
+
 ## clipboard
 
 write to or read from clipboard

package/endpoint.js

@@ -0,0 +1,163 @@
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const axios = require('axios')
+
+const DEFAULT_PROTOCOL = 'http'
+const DEFAULT_HOST = '127.0.0.1'
+const DEFAULT_PORT = 42000
+const DEFAULT_BASE_URL = `${DEFAULT_PROTOCOL}://${DEFAULT_HOST}:${DEFAULT_PORT}`
+const CONFIG_PATH = path.resolve(os.homedir(), '.pinokio', 'config.json')
+
+let resolvedHttpBaseUrlPromise = null
+
+function formatHostForUrl(host) {
+  if (!host) {
+    return ''
+  }
+  const normalized = String(host).trim().replace(/^\[|\]$/g, '')
+  if (!normalized) {
+    return ''
+  }
+  return normalized.includes(':') ? `[${normalized}]` : normalized
+}
+
+function normalizeBaseUrl(value) {
+  if (typeof value !== 'string') {
+    return null
+  }
+  const trimmed = value.trim()
+  if (!trimmed) {
+    return null
+  }
+  try {
+    const url = new URL(trimmed)
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+      return null
+    }
+    return `${url.protocol}//${url.host}`
+  } catch (error) {
+    return null
+  }
+}
+
+function buildExplicitHttpBaseUrl(target) {
+  if (!target) {
+    return null
+  }
+  if (typeof target === 'string') {
+    const normalized = normalizeBaseUrl(target)
+    if (normalized) {
+      return normalized
+    }
+    const host = formatHostForUrl(target)
+    if (!host) {
+      return null
+    }
+    return normalizeBaseUrl(`${DEFAULT_PROTOCOL}://${host}:${DEFAULT_PORT}`)
+  }
+  if (typeof target !== 'object') {
+    return null
+  }
+  const protocol = target.protocol === 'https' ? 'https' : DEFAULT_PROTOCOL
+  const host = formatHostForUrl(target.host)
+  if (!host) {
+    return null
+  }
+  const rawPort = Number.parseInt(String(target.port), 10)
+  const port = Number.isFinite(rawPort) && rawPort > 0 ? rawPort : DEFAULT_PORT
+  return normalizeBaseUrl(`${protocol}://${host}:${port}`)
+}
+
+function readStoredAccessBaseUrl() {
+  try {
+    const raw = fs.readFileSync(CONFIG_PATH, 'utf8')
+    const parsed = JSON.parse(raw)
+    const access = parsed && parsed.access
+    if (!access) {
+      return null
+    }
+    if (typeof access === 'string') {
+      const value = access.trim()
+      if (!value) {
+        return null
+      }
+      if (/^https?:\/\//i.test(value)) {
+        return normalizeBaseUrl(value)
+      }
+      if (/^\[.*\](?::\d+)?$/.test(value) || /:\d+$/.test(value)) {
+        return normalizeBaseUrl(`${DEFAULT_PROTOCOL}://${value}`)
+      }
+      return normalizeBaseUrl(`${DEFAULT_PROTOCOL}://${formatHostForUrl(value)}:${DEFAULT_PORT}`)
+    }
+    if (typeof access !== 'object') {
+      return null
+    }
+    const protocol = access.protocol === 'https' ? 'https' : DEFAULT_PROTOCOL
+    const host = formatHostForUrl(access.host)
+    if (!host) {
+      return null
+    }
+    const rawPort = Number.parseInt(String(access.port), 10)
+    const port = Number.isFinite(rawPort) && rawPort > 0 ? rawPort : DEFAULT_PORT
+    return normalizeBaseUrl(`${protocol}://${host}:${port}`)
+  } catch (error) {
+    return null
+  }
+}
+
+async function canReachControlPlane(baseUrl) {
+  try {
+    await axios.get(`${baseUrl}/pinokio/version`, {
+      timeout: 1000,
+      headers: {
+        'x-pinokio-client': 'pterm'
+      },
+      validateStatus: () => true
+    })
+    return true
+  } catch (error) {
+    return false
+  }
+}
+
+async function resolveHttpBaseUrl(target) {
+  const explicitBaseUrl = buildExplicitHttpBaseUrl(target)
+  if (explicitBaseUrl) {
+    return explicitBaseUrl
+  }
+  if (!resolvedHttpBaseUrlPromise) {
+    resolvedHttpBaseUrlPromise = (async () => {
+      if (await canReachControlPlane(DEFAULT_BASE_URL)) {
+        return DEFAULT_BASE_URL
+      }
+      return readStoredAccessBaseUrl() || DEFAULT_BASE_URL
+    })()
+  }
+  try {
+    return await resolvedHttpBaseUrlPromise
+  } catch (error) {
+    resolvedHttpBaseUrlPromise = null
+    throw error
+  }
+}
+
+async function resolveWsBaseUrl(target) {
+  const httpBaseUrl = await resolveHttpBaseUrl(target)
+  const normalized = normalizeBaseUrl(httpBaseUrl)
+  if (!normalized) {
+    return `ws://${DEFAULT_HOST}:${DEFAULT_PORT}`
+  }
+  const url = new URL(normalized)
+  url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:'
+  return `${url.protocol}//${url.host}`
+}
+
+module.exports = {
+  DEFAULT_BASE_URL,
+  DEFAULT_PORT,
+  buildExplicitHttpBaseUrl,
+  readStoredAccessBaseUrl,
+  resolveHttpBaseUrl,
+  resolveWsBaseUrl,
+}

package/index.js

@@ -1,18 +1,64 @@
 #!/usr/bin/env node
 const path = require('path')
+const axios = require('axios')
 const yargs = require('yargs/yargs')
 const { hideBin } = require('yargs/helpers')
+const { resolveHttpBaseUrl } = require('./endpoint')
+const { isHttpUri, resolveAppControlTarget, resolveStartTarget } = require('./target')
+const extractStartInput = (parsedArgv) => {
+  const rawScriptArgs = Array.isArray(parsedArgv && parsedArgv["--"]) ? parsedArgv["--"] : []
+  if (!rawScriptArgs.length) {
+    return undefined
+  }
+  const scriptArgv = yargs(rawScriptArgs)
+    .parserConfiguration({
+      'camel-case-expansion': false,
+      'dot-notation': false,
+      'duplicate-arguments-array': true,
+      'populate--': false
+    })
+    .help(false)
+    .version(false)
+    .parse()
+  const input = {}
+  for (const [key, value] of Object.entries(scriptArgv || {})) {
+    if (key === '_' || key === '$0' || value === undefined) {
+      continue
+    }
+    input[key] = value
+  }
+  return Object.keys(input).length > 0 ? input : undefined
+}
 const argv = yargs(hideBin(process.argv))
   .option('default', {
     type: 'string',
     array: true
   })
+  .option('peer', {
+    type: 'string'
+  })
+  .option('surface', {
+    type: 'string'
+  })
+  .option('preset', {
+    type: 'string'
+  })
+  .option('ref', {
+    type: 'string'
+  })
+  .parserConfiguration({
+    'populate--': true
+  })
   .parse();
 const Script = require('./script')
 const Util = require('./util')
 const script = new Script();
 const util = new Util();
-const isHttpUri = (value) => typeof value === "string" && /^https?:\/\//i.test(value);
+const fetchPinokioVersion = async () => {
+  const baseUrl = await resolveHttpBaseUrl()
+  const response = await axios.get(`${baseUrl}/pinokio/version`)
+  return response.data
+}
 (async () => {
   if (argv._.length > 0) {
     let cmd = argv._[0].toLowerCase()
@@ -27,27 +73,21 @@ const isHttpUri = (value) => typeof value === "string" && /^https?:\/\//i.test(v
           console.log("pterm@" + require('./package.json').version)
         } else if (app === "pinokiod") {
           try {
-            let r = await fetch("http://localhost:42000/pinokio/version").then((res) => {
-              return res.json()
-            })
+            let r = await fetchPinokioVersion()
             console.log(`pinokiod@${r.pinokiod}`)
           } catch (e) {
           }
         } else if (app === "pinokio") {
           try {
-            let r = await fetch("http://localhost:42000/pinokio/version").then((res) => {
-              return res.json()
-            })
+            let r = await fetchPinokioVersion()
             if (r.pinokio) {
-              console.log(`pinokiod@${r.pinokio}`)
+              console.log(`pinokio@${r.pinokio}`)
             }
           } catch (e) {
           }
         } else if (app === "script") {
           try {
-            let r = await fetch("http://localhost:42000/pinokio/version").then((res) => {
-              return res.json()
-            })
+            let r = await fetchPinokioVersion()
             if (r.script) {
               console.log(`${r.script}`)
             }
@@ -57,8 +97,10 @@ const isHttpUri = (value) => typeof value === "string" && /^https?:\/\//i.test(v
       }
     } else if (cmd === "filepicker") {
       await util.filepicker(argv)
+    } else if (cmd === "upload") {
+      await util.upload(argv)
     } else if (cmd === "download") {
-      await util.download(argv)
+      await util.appDownload(argv)
     } else if (cmd === "registry") {
       const subcmd = argv._.length > 1 ? String(argv._[1]).toLowerCase() : ""
       if (subcmd === "search") {
@@ -82,19 +124,27 @@ const isHttpUri = (value) => typeof value === "string" && /^https?:\/\//i.test(v
       await util.status(argv)
     } else if (cmd === "logs") {
       await util.logs(argv)
+    } else if (cmd === "open") {
+      await util.open(argv)
     } else if (cmd === "stop") {
       await script.stop(argv)
     } else if (cmd === "start") {
       if (argv._.length > 1) {
         let uri = argv._[1]
-        await script.start(uri, true) 
+        const startTarget = await resolveStartTarget(uri, argv.ref)
+        const startInput = extractStartInput(argv)
+        const startPayload = startInput
+          ? { uri: startTarget.uri, input: startInput }
+          : startTarget.uri
+        await script.start(startPayload, true, null, startTarget.controlPlane)
       } else {
         console.error("required argument: <uri>")
       }
     } else if (cmd === "run") {
       if (argv._.length > 1) {
         let _uri = argv._[1]
-        const uri = isHttpUri(_uri) ? _uri : path.resolve(process.cwd(), _uri)
+        const runTarget = await resolveAppControlTarget(_uri)
+        const uri = runTarget.uri
         // try downloading first
         if (isHttpUri(uri)) {
           await util.download({
@@ -102,16 +152,18 @@ const isHttpUri = (value) => typeof value === "string" && /^https?:\/\//i.test(v
             no_exit: true
           })
         }
+        let launched = false
         while(true) {
-          let default_target = await script.default_script(uri, argv.default)
+          let default_target = await script.default_script(uri, argv.default, runTarget.controlPlane)
           if (default_target) {
+            launched = true
             if (path.isAbsolute(default_target.uri)) {
               await new Promise((resolve, reject) => {
                 script.start(default_target, false, (packet) => {
                   if (packet.type === "result") {
                     resolve()
                   }
-                })
+                }, runTarget.controlPlane)
               })
               if (script.killed) {
                 break
@@ -133,6 +185,9 @@ const isHttpUri = (value) => typeof value === "string" && /^https?:\/\//i.test(v
         if (script.killed) {
           process.exit()
         }
+        if (!launched) {
+          process.exit(0)
+        }
       } else {
         console.error("required argument: <uri>")
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pterm",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "description": "",
   "main": "index.js",
   "bin": {