@telepath-computer/television 0.1.190 → 0.1.192

package/dist/cli.cjs

@@ -33250,6 +33250,7 @@ var require_websocket_server = __commonJS({
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  PORT_ZERO_WARNING: () => PORT_ZERO_WARNING,
   inspectTelemetryBuildConfig: () => inspectTelemetryBuildConfig,
   listVisibleCLICommandNames: () => listVisibleCLICommandNames,
   resolveBundledSkillsRoot: () => resolveBundledSkillsRoot,
@@ -34039,7 +34040,10 @@ var ScreenClient = class {
     if (screens.length === 1) {
       return screens[0].id;
     }
-    throw this.#http.createError(
+    if (screens.length === 0) {
+      throw new ValidationError("screenID is required, but no screens exist.");
+    }
+    throw new ValidationError(
       `screenID is required when multiple screens exist. Available screens: ${formatScreenChoices(screens)}`
     );
   }
@@ -34219,6 +34223,7 @@ var TELEVISION_STORAGE_PATH_ENV = "TELEVISION_STORAGE_PATH";
 var TELEVISION_PORT_ENV = "TELEVISION_PORT";
 var TELEVISION_ACP_AGENT_ENV = "TELEVISION_ACP_AGENT";
 var TELEVISION_DEVELOPER_HOME_ENV = "TELEVISION_DEVELOPER_HOME";
+var MAX_PORT = 65535;
 var TELEMETRY_CONTROL_ENV_VARS = [
   "DO_NOT_TRACK",
   "CI",
@@ -34259,11 +34264,17 @@ function getTelevisionStoragePath() {
 }
 function getTelevisionPortEnv() {
   const rawPort = process.env[TELEVISION_PORT_ENV];
-  if (!rawPort) {
+  if (rawPort === void 0 || rawPort.trim() === "") {
     return void 0;
   }
-  const port = Number.parseInt(rawPort, 10);
-  return Number.isInteger(port) ? port : void 0;
+  if (!/^\d+$/.test(rawPort)) {
+    throw new Error(`${TELEVISION_PORT_ENV} must be a decimal integer between 0 and ${MAX_PORT}.`);
+  }
+  const port = Number(rawPort);
+  if (!Number.isSafeInteger(port) || port < 0 || port > MAX_PORT) {
+    throw new Error(`${TELEVISION_PORT_ENV} must be a decimal integer between 0 and ${MAX_PORT}.`);
+  }
+  return port;
 }
 function resolveACPAgentProfile(env = process.env) {
   const rawAgent = env[TELEVISION_ACP_AGENT_ENV];
@@ -52558,7 +52569,7 @@ function disabledTelemetryRuntime() {
 
 // ../server/src/updates/version.ts
 function readVersionStamp() {
-  if ("0.1.190".length > 0) return "0.1.190";
+  if ("0.1.192".length > 0) return "0.1.192";
   return void 0;
 }
 function resolveUpdateReleaseVersion(env = process.env, stamp = readVersionStamp()) {
@@ -53058,8 +53069,8 @@ var Server = class {
   };
 };
 function readServerPackageVersion() {
-  if ("0.1.190".length > 0) {
-    return telemetryVersion("0.1.190");
+  if ("0.1.192".length > 0) {
+    return telemetryVersion("0.1.192");
   }
   const packageJsonPath = import_node_path11.default.resolve(import_node_path11.default.dirname((0, import_node_url.fileURLToPath)(import_meta.url)), "..", "package.json");
   if (!(0, import_node_fs9.existsSync)(packageJsonPath)) return telemetryVersion("0.0.0");
@@ -54575,10 +54586,12 @@ var import_meta2 = {};
 var DAEMON_NAME = "com.television.server";
 var TELEMETRY_LAUNCH_MODE_ENV = "TELEVISION_LAUNCH_MODE";
 var SKILL_INSTALL_TELEMETRY_TIMEOUT_MS2 = 1e3;
-var MAX_PORT = 65535;
+var MAX_PORT2 = 65535;
 var MAX_PROCESS_EXIT_STATUS = 255;
 var HTTP_UNAUTHORIZED_STATUS2 = 401;
 var HELP_POINTER = "Television ships bundled skills. The main skill is `television` \u2014 keep its guidance available for screens, lifecycle, the `tv` CLI, and artifact workflow. Re-read it only if it is not already in context or you know the installed skill changed. Additional `tv-*` skills cover specialized artifact types and theming. Install all bundled skills with `tv skills install <path>` (e.g. ~/.openclaw/skills) or `tv skills install -i`.";
+var PORT_ZERO_WARNING = "WARNING: --port 0 can make Television hard for later agent CLI commands to rediscover. Use a stable port and export TELEVISION_PORT in the user's environment when agents need to find the server later.";
+var SAFE_ARG_PATTERN = /^[A-Za-z0-9_./:@%+=,-]+$/;
 var CLIDirectiveError = class extends Error {
   name = "CLIDirectiveError";
 };
@@ -54636,8 +54649,8 @@ function resolveVercelSkillsInstallerBin() {
   return localRequire.resolve("skills/bin/cli.mjs");
 }
 function readCLIVersion() {
-  if ("0.1.190".length > 0) {
-    return "0.1.190";
+  if ("0.1.192".length > 0) {
+    return "0.1.192";
   }
   const devPackageJsonPath = import_node_path17.default.join(getDevPackageDir(), "package.json");
   if (!(0, import_node_fs14.existsSync)(devPackageJsonPath)) {
@@ -54682,9 +54695,14 @@ function buildArtifactWorkflowHelpNote(includeHTMLNote) {
   }
   return lines.join("\n");
 }
-function commandNameFromArgv(argv) {
-  const parts = argv.filter((value) => !value.startsWith("-"));
-  return parts.length > 0 ? parts.join(" ") : "tv";
+function formatArgvToken(value) {
+  return SAFE_ARG_PATTERN.test(value) ? value : JSON.stringify(value);
+}
+function formatEnteredInvocation(argv) {
+  return ["tv", ...argv.map(formatArgvToken)].join(" ");
+}
+function formatEnteredCommand(argv) {
+  return argv.length > 0 ? argv.map(formatArgvToken).join(" ") : "tv";
 }
 function storagePathFromArgv(argv) {
   for (let index = 0; index < argv.length; index += 1) {
@@ -54707,6 +54725,9 @@ function formatCLIError(error48, argv = []) {
   if (error48 instanceof CLIDirectiveError) {
     return error48.message;
   }
+  if (error48 instanceof ValidationError) {
+    return ensureHelpPointer(error48.message);
+  }
   if (typeof error48 === "object" && error48 !== null && "serverURL" in error48 && "message" in error48) {
     const serverURL = String(error48.serverURL);
     const message = String(error48.message);
@@ -54724,9 +54745,12 @@ function formatCLIError(error48, argv = []) {
   return error48 instanceof Error ? error48.message : String(error48);
 }
 function parsePortOption(value) {
-  const port = Number.parseInt(value, 10);
-  if (!Number.isInteger(port) || port < 0 || port > MAX_PORT) {
-    throw new InvalidArgumentError(`port must be an integer between 0 and ${MAX_PORT}`);
+  if (!/^\d+$/.test(value)) {
+    throw new InvalidArgumentError(`port must be a decimal integer between 0 and ${MAX_PORT2}`);
+  }
+  const port = Number(value);
+  if (!Number.isSafeInteger(port) || port < 0 || port > MAX_PORT2) {
+    throw new InvalidArgumentError(`port must be a decimal integer between 0 and ${MAX_PORT2}`);
   }
   return port;
 }
@@ -54734,7 +54758,14 @@ function collectOption(value, previous = []) {
   return [...previous, value];
 }
 function resolveClientPort(port) {
-  return port ?? getTelevisionPortEnv() ?? DEFAULT_SERVER_PORT;
+  if (port !== void 0) {
+    return port;
+  }
+  try {
+    return getTelevisionPortEnv() ?? DEFAULT_SERVER_PORT;
+  } catch (error48) {
+    throw createDirectiveError(error48 instanceof Error ? error48.message : String(error48));
+  }
 }
 function buildLocalServerURL(port) {
   return buildServerURL(DEFAULT_SERVER_HOST, resolveClientPort(port));
@@ -54753,12 +54784,13 @@ function resolveServeAuth(argv, hasListen) {
   return void 0;
 }
 function resolveStaticDir() {
-  if (!process.argv[1]) {
-    return void 0;
+  if (process.argv[1]) {
+    const entryDir = import_node_path17.default.dirname((0, import_node_fs14.realpathSync)(process.argv[1]));
+    const resolved = import_node_path17.default.resolve(entryDir, "./web");
+    return (0, import_node_fs14.existsSync)(import_node_path17.default.join(resolved, "index.html")) ? resolved : void 0;
   }
-  const entryDir = import_node_path17.default.dirname((0, import_node_fs14.realpathSync)(process.argv[1]));
-  const resolved = import_node_path17.default.resolve(entryDir, "./web");
-  return (0, import_node_fs14.existsSync)(import_node_path17.default.join(resolved, "index.html")) ? resolved : void 0;
+  const devStaticPath = import_node_path17.default.resolve(getDevPackageDir(), "../web/dist");
+  return (0, import_node_fs14.existsSync)(import_node_path17.default.join(devStaticPath, "index.html")) ? devStaticPath : void 0;
 }
 function resolveBundledViewsPath() {
   if (process.argv[1]) {
@@ -54867,29 +54899,30 @@ function formatScreenRemovalResult(result) {
   return header;
 }
 function formatCommanderError(argv, error48) {
-  const commandName = commandNameFromArgv(argv);
+  const enteredInvocation = formatEnteredInvocation(argv);
+  const enteredCommand = formatEnteredCommand(argv);
   const optionMatch = /option '([^']+)'/.exec(error48.message);
   const argumentMatch = /missing required argument '([^']+)'/.exec(error48.message);
   if (error48.code === "commander.unknownCommand") {
-    return createDirectiveError(`Unknown tv command: ${commandName}.`);
+    return createDirectiveError(`Unknown tv command: ${enteredCommand}.`);
   }
-  if (commandName === "help" && error48.code === "commander.excessArguments") {
-    return createDirectiveError("tv help does not accept additional arguments.");
+  if (argv[0] === "help" && error48.code === "commander.excessArguments") {
+    return createDirectiveError(`${enteredInvocation} does not accept additional arguments.`);
   }
   if (error48.code === "commander.unknownOption") {
     const optionText = optionMatch?.[1] ?? "that option";
-    return createDirectiveError(`tv ${commandName} does not support ${optionText}.`);
+    return createDirectiveError(`${enteredInvocation} does not support ${optionText}.`);
   }
   if (error48.code === "commander.missingMandatoryOptionValue") {
     const optionText = optionMatch?.[1] ?? "the required option";
-    return createDirectiveError(`tv ${commandName} requires ${optionText}.`);
+    return createDirectiveError(`${enteredInvocation} requires ${optionText}.`);
   }
   if (error48.code === "commander.missingArgument") {
     const argumentText = argumentMatch ? `<${argumentMatch[1]}>` : "the required argument";
-    return createDirectiveError(`tv ${commandName} requires ${argumentText}.`);
+    return createDirectiveError(`${enteredInvocation} requires ${argumentText}.`);
   }
   if (error48.code === "commander.invalidArgument") {
-    return createDirectiveError(`tv ${commandName} received an invalid argument: ${error48.message.replace(/^error:\s*/, "")}`);
+    return createDirectiveError(`${enteredInvocation} received an invalid argument: ${error48.message.replace(/^error:\s*/, "")}`);
   }
   return null;
 }
@@ -54939,7 +54972,7 @@ function createEnvironment(environment) {
     createServer: environment.createServer ?? ((options) => new Server({
       // `tv serve` always enables the onboarding installer, passing the
       // resolved content root when one resolved
-      // (specs/arch/onboarding/content.md CLI path resolution).
+      // (specs/arch/cli/index.md, build and packaged asset layout).
       store: new ServerStore({
         storagePath: options.storagePath ?? getTelevisionStoragePath(),
         ...options.bundledViewsPath ? { bundledViewsPath: options.bundledViewsPath } : {},
@@ -54989,7 +55022,13 @@ function resolveClientStoragePath(storagePath) {
 }
 function createProgram(env, argv = []) {
   const program2 = new Command();
+  const warnForExplicitPortZero = (port) => {
+    if (port === 0) {
+      writeLine(env.stderr, PORT_ZERO_WARNING);
+    }
+  };
   const createAuthenticatedClient = (options = {}) => {
+    warnForExplicitPortZero(options.port);
     return env.createClient(
       buildLocalServerURL(options.port),
       readAuthToken(resolveClientStoragePath(options.storagePath))
@@ -55017,7 +55056,7 @@ function createProgram(env, argv = []) {
     log(storagePath, "persisted service uninstalled", { daemonName: DAEMON_NAME, outcome });
     writeJSON(env.stdout, { status: "stopped" });
   };
-  program2.name("tv").description("Television \u2014 virtual display for agents").version(readCLIVersion()).showSuggestionAfterError(false).addHelpText("after", buildAgentHelpNote()).configureOutput({
+  program2.name("tv").description("Television \u2014 virtual display for agents").version(readCLIVersion()).option("-v", "Output the version number").showSuggestionAfterError(false).addHelpText("after", buildAgentHelpNote()).configureOutput({
     writeOut: (str) => env.stdout.write(str),
     writeErr: (str) => env.stderr.write(str),
     outputError: () => {
@@ -55041,11 +55080,21 @@ function createProgram(env, argv = []) {
       throw error48;
     }
     if (opts.persist) {
+      if (opts.port === 0) {
+        throw createDirectiveError(
+          "tv serve --persist --port 0 requires a stable port; port 0 lets the operating system choose a runtime port and cannot produce a stable persisted-service startup URL. Set TELEVISION_PORT to a stable port or pass a non-zero --port."
+        );
+      }
+      const clientPort = resolveClientPort(opts.port);
       const storagePath = import_node_path17.default.resolve(opts.storagePath ?? getTelevisionStoragePath());
       const profile2 = resolveACPAgentProfile(process.env);
       const daemonEnv = buildPersistedACPEnvironment(process.env, { developerHome: env.resolveHomeDir() });
-      if (process.env.TELEVISION_PORT !== void 0) daemonEnv.TELEVISION_PORT = process.env.TELEVISION_PORT;
-      if (process.env.TELEVISION_STORAGE_PATH !== void 0) daemonEnv.TELEVISION_STORAGE_PATH = process.env.TELEVISION_STORAGE_PATH;
+      if (process.env.TELEVISION_PORT !== void 0 && process.env.TELEVISION_PORT !== "") {
+        daemonEnv.TELEVISION_PORT = process.env.TELEVISION_PORT;
+      }
+      if (process.env.TELEVISION_STORAGE_PATH !== void 0 && process.env.TELEVISION_STORAGE_PATH !== "") {
+        daemonEnv.TELEVISION_STORAGE_PATH = process.env.TELEVISION_STORAGE_PATH;
+      }
       daemonEnv[TELEMETRY_LAUNCH_MODE_ENV] = "daemon";
       if (profile2 && !isACPCommandResolvable(profile2.command, daemonEnv)) {
         const error48 = createDirectiveError(
@@ -55086,14 +55135,14 @@ function createProgram(env, argv = []) {
         });
         throw error48;
       }
-      const port = resolveClientPort(opts.port);
-      const serverURLs2 = resolveBindAddresses(opts.listen).map((address) => buildServerURL(address, port));
+      const serverURLs2 = resolveBindAddresses(opts.listen).map((address) => buildServerURL(address, clientPort));
       writeConnectURLs(env.stdout, serverURLs2, {
         installed: true,
         token: auth === true ? readOrCreateAuthToken(storagePath) : null
       });
       return;
     }
+    warnForExplicitPortZero(opts.port);
     const profile = resolveACPAgentProfile(process.env);
     if (profile && !isACPCommandResolvable(profile.command, process.env)) {
       const error48 = createDirectiveError(
@@ -55163,10 +55212,11 @@ function createProgram(env, argv = []) {
     "Create a URL artifact that points at an absolute http(s) URL. Television records the pointer only and does not own or modify the remote page."
   ).requiredOption("--screen <id>", "Target screen ID").requiredOption("--title <title>", "Artifact title").requiredOption("--url <url>", "http(s) URL").option("--focus-artifact", "Focus the new artifact after creation").option("--no-focus", "Create the artifact in the background without changing focus").option("--port <number>", "Server port", parsePortOption).option("--storage-path <path>", "Directory containing the Television token").addHelpText("after", buildArtifactWorkflowHelpNote(true)).action(async (opts) => {
     const shouldFocus = resolveFocusDirective(argv, "create-url-artifact", "--focus-artifact");
+    const artifactURL = opts.url.trim();
     const client = createAuthenticatedClient(opts);
     const { artifact } = await client.artifacts.create({
       kind: "url",
-      url: opts.url,
+      url: artifactURL,
       title: opts.title,
       screenID: opts.screen
     });
@@ -55174,7 +55224,7 @@ function createProgram(env, argv = []) {
       await client.display.focus({ artifactID: artifact.id });
     }
     writeLine(env.stdout, `URL artifact ${artifact.id} created.`);
-    writeLine(env.stdout, `Television registered ${opts.url}.`);
+    writeLine(env.stdout, `Television registered ${artifactURL}.`);
   });
   program2.command("storage-path").description("Print the Television storage path").action(() => {
     writeJSON(env.stdout, { storagePath: getTelevisionStoragePath() });
@@ -55290,7 +55340,7 @@ function createProgram(env, argv = []) {
     "Examples: ~/.openclaw/skills, ~/.hermes/skills, ~/.agents/skills.",
     "`tv skills install -i` runs the external skills installer against Television's bundled skills root."
   ].join("\n"));
-  skillsCommand.command("install").description("Copy bundled Television skills into an agent harness skills folder, or run the external installer against the bundled skills root").argument("[path]", "Destination agent skills folder (for example: ~/.openclaw/skills, ~/.hermes/skills, ~/.agents/skills)").option("-i, --interactive", "Run the external skills installer against the bundled Television skills root").option("--installed-by-agent <agent-runtime-harness-name>", "Agent runtime harness name performing this install").allowUnknownOption(true).action(async function(inputPath, opts) {
+  skillsCommand.command("install").description("Copy bundled Television skills into an agent harness skills folder, or run the external installer against the bundled skills root").argument("[path]", "Destination agent skills folder (for example: ~/.openclaw/skills, ~/.hermes/skills, ~/.agents/skills)").option("-i, --interactive", "Run the external skills installer against the bundled Television skills root").option("--installed-by-agent <agent-runtime-harness-name>", "Agent runtime harness name performing this install").action(async function(inputPath, opts) {
     const bundledTelevisionSkillsCollectionRoot = env.resolveBundledSkillsRoot();
     if (opts.interactive) {
       if (inputPath) {
@@ -55373,6 +55423,10 @@ function listVisibleCLICommandNames() {
 async function runCLI(argv, environment = {}) {
   const env = createEnvironment(environment);
   try {
+    if (argv.length === 1 && argv[0] === "-v") {
+      writeLine(env.stdout, readCLIVersion());
+      return 0;
+    }
     const program2 = createProgram(env, argv);
     if (argv.length === 0) {
       program2.outputHelp();
@@ -55405,6 +55459,7 @@ if (!isVitestRuntime()) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  PORT_ZERO_WARNING,
   inspectTelemetryBuildConfig,
   listVisibleCLICommandNames,
   resolveBundledSkillsRoot,