@unaquatic/flow 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aquatic
+
+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/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+<p align="center">
+  <a href="https://github.com/unaquatic/flow">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="docs/logo-dark.svg">
+      <img src="docs/logo-light.svg" alt="flow">
+    </picture>
+  </a>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <a href="https://go.dev/"><img src="https://img.shields.io/badge/Go-1.27-555?labelColor=888&logo=go&logoColor=white&style=flat-square" alt="Go"></a>
+  <a href="https://github.com/unaquatic/flow/blob/main/LICENSE"><img src="https://img.shields.io/github/license/unaquatic/flow?labelColor=888&color=555&style=flat-square" alt="License"></a>
+  <a href="https://github.com/unaquatic/flow/stargazers"><img src="https://img.shields.io/github/stars/unaquatic/flow?labelColor=888&color=555&style=flat-square" alt="GitHub stars"></a>
+</p>
+
+<p align="center"><b>A tiny and fast agent written in golang.</b></p>
+
+---
+
+
+## Installation
+
+```sh
+curl -fsSL https://aquatic.dev/flow/install | sh   # macOS, Linux, Git Bash on Windows
+npm install -g @unaquatic/flow
+pnpm add -g @unaquatic/flow
+```
+
+The install script downloads flow from its GitHub release, checked against
+the digest GitHub reports for it, puts it in `~/.flow/bin`, links it from
+`~/.local/bin`, and adds that to `PATH`. `FLOW_VERSION`, `FLOW_INSTALL_DIR` and
+`FLOW_NO_MODIFY_PATH=1` change what it does.
+
+On Windows, flow runs in Windows Terminal or any Windows 10+ console. Its bash
+tool runs commands with Git Bash, so install
+[Git for Windows](https://git-scm.com/download/win), or put another
+`bash.exe` on `PATH`.
+
+## Updating
+
+When it starts, flow checks for a newer release where it was installed from:
+GitHub for the install script, npm for npm and pnpm. It installs the release
+in the background the same way, and runs it from the next start, which shows
+`Updated to v1.2.3` under the status. Install output goes to
+`~/.flow/logs/update.log`. Windows cannot replace a running flow, so there
+flow updates only when you run `flow update`.
+
+```sh
+flow update          # install the latest release now
+flow update --check  # only check for one
+```
+
+Set `"auto_update": false` in `~/.flow/config.json`, or
+`FLOW_DISABLE_AUTOUPDATE=1`, to turn off the background check and install.
+
+## Development
+
+Build and run from source with Go 1.27+.
+
+```sh
+go build ./cmd/flow/
+./flow
+```
+
+## License
+
+Flow is released under the [MIT License](LICENSE).

package/bin/flow.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// Runs the flow binary for this platform.
+"use strict";
+
+const { spawn } = require("node:child_process");
+const { existsSync, realpathSync } = require("node:fs");
+const path = require("node:path");
+
+const { name } = require("../package.json");
+const root = realpathSync(path.join(__dirname, ".."));
+
+// Errors read as the install script's, with "error:" in red on a terminal.
+function fail(message) {
+  const color = process.stderr.isTTY && !process.env.NO_COLOR && process.env.TERM !== "dumb";
+  console.error(`${color ? "\x1b[31merror:\x1b[39m" : "error:"} flow: ${message}`);
+  process.exit(1);
+}
+
+// The package holds a binary for every platform, next to this file, with .exe
+// on Windows.
+const windows = process.platform === "win32";
+const bin = path.join(__dirname, `flow-${process.platform}-${process.arch}${windows ? ".exe" : ""}`);
+if (!existsSync(bin)) {
+  fail(`unsupported platform: ${process.platform}/${process.arch}`);
+}
+
+// Tells flow whether pnpm or npm installed it, so it updates with the same one.
+// pnpm marks its node_modules with .modules.yaml.
+function managedBy() {
+  for (let dir = root; dir !== path.dirname(dir); dir = path.dirname(dir)) {
+    const modules = path.join(dir, "node_modules");
+    try {
+      if (existsSync(path.join(modules, ".modules.yaml")) && realpathSync(path.join(modules, name)) === root) {
+        return "pnpm";
+      }
+    } catch {}
+  }
+  return "npm";
+}
+
+const child = spawn(bin, process.argv.slice(2), {
+  stdio: "inherit",
+  env: { ...process.env, FLOW_MANAGED_BY: managedBy() },
+});
+child.on("error", (err) => fail(`launch failed: ${err.message}`));
+
+// Pass stop signals on to flow. On Windows the console sends Ctrl-C to flow
+// as well, and child.kill would end flow at once, without its cleanup, so the
+// launcher only stays alive until flow exits.
+const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+for (const signal of signals) {
+  process.on(signal, () => {
+    if (!windows) {
+      child.kill(signal);
+    }
+  });
+}
+
+// Exit the way flow exited.
+child.on("exit", (code, signal) => {
+  if (signal) {
+    for (const s of signals) {
+      process.removeAllListeners(s);
+    }
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 1);
+});

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@unaquatic/flow",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A tiny and fast agent written in golang.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unaquatic/flow.git"
+  },
+  "bin": {
+    "flow": "bin/flow.js"
+  },
+  "files": [
+    "bin"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "arm64",
+    "x64"
+  ]
+}