@fnnas-labs/fnos-cli 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guangzhou TR Intelligent Manufacturing Technology Co., Ltd.
+
+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,170 @@
-# Temporary Holding Version
+# @fnnas-labs/fnos-cli
 
-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.
+The command-line client and Agent Skill for fnOS. It supports macOS, Linux,
+and Windows on x64 and arm64.
+
+## Quick Start
+
+Node.js 18 or later and `npx` are required:
+
+```bash
+npx -y --package=@fnnas-labs/fnos-cli@0.2.0 fnos-cli install
+fnos-cli --help
+```
+
+The install command performs two actions:
+
+- installs the same version of the `fnos-cli` command globally through npm;
+- installs the matching fnOS Agent Skill in `~/.agents/skills/fnos-cli`.
+
+The package also exposes `trim-cli` as a compatibility command. Both commands
+launch the same CLI and report the same version.
+
+Both names retain the existing `~/.config/trim-cli` session location, the
+`TRIM_CLI_CONFIG_DIR` override, named `--profile` sessions and the macOS Keychain
+identity `trim-cli.session`. Upgrading the command name alone does not require
+another authorization. Use the same host, system user, configuration environment
+and profile as your login terminal; SSH, containers and other hosts do not
+automatically share that session. Existing sessions must still have the current
+OAuth permissions.
+
+Codex and other compatible agents can discover `SKILL.md` from that directory.
+Restart an already running agent if the newly installed Skill does not appear.
+
+## Other Installation Modes
+
+```bash
+# Install only the Skill without installing the global fnos-cli command
+npx -y --package=@fnnas-labs/fnos-cli@0.2.0 fnos-cli install --skill-only
+
+# Install the Skill in .agents/skills/fnos-cli under the current project
+npx -y --package=@fnnas-labs/fnos-cli@0.2.0 fnos-cli install --project
+
+# Install only the global fnos-cli command without copying the Skill
+npx -y --package=@fnnas-labs/fnos-cli@0.2.0 fnos-cli install --skip-skill
+```
+
+You can also run the CLI without installing it permanently:
+
+```bash
+npx -y --package=@fnnas-labs/fnos-cli@0.2.0 fnos-cli --help
+npx -y --package=@fnnas-labs/fnos-cli@0.2.0 fnos-cli --version
+```
+
+The npm package contains native binaries for every supported platform. The
+launcher selects the correct binary for the current operating system and CPU
+architecture. Unsupported platforms are rejected before the CLI starts.
+
+## Sign In to fnOS
+
+Installation does not sign in automatically, enter account credentials, or
+open an authorization page. Start the interactive OAuth PKCE flow before first
+use:
+
+```bash
+fnos-cli --profile home --host <nas-host> --port <port> login
+```
+
+The production authorization flow is:
+
+1. The CLI displays an authorization URL.
+2. The user signs in and approves access in a browser.
+3. The user pastes the one-time code back into the CLI prompt.
+
+Use `--no-open` when the CLI cannot open a browser automatically:
+
+```bash
+fnos-cli --profile home --host <nas-host> --port <port> login --no-open
+```
+
+Remote devices using unencrypted HTTP must be explicitly allowed:
+
+```bash
+fnos-cli --profile home --host <nas-host> --port 5666 \
+  --scheme http --allow-insecure-http login --no-open
+```
+
+After signing in, commands can be run as follows:
+
+```bash
+fnos-cli --profile home system info
+fnos-cli --profile home file ls /vol1
+fnos-cli --profile home photos folders
+fnos-cli --profile home docker container ls --all
+```
+
+Write operations still require an explicit `--yes`. Do not include an
+authorization code, access token, or refresh token in command arguments, logs,
+or error reports.
+
+## Update and Uninstall
+
+Run the installation command again with the version you intend to install:
+
+```bash
+npx -y --package=@fnnas-labs/fnos-cli@0.2.0 fnos-cli install
+```
+
+The installer writes `.fnos-cli-ownership.json` inside the installed Skill,
+recording its package, version and SHA-256 digest manifest. It replaces an
+existing `fnos-cli` Skill only when that marker and the complete directory tree
+still agree. Added files, empty directories, edited files or symbolic links make
+the directory ineligible for automatic replacement. An unknown or customized
+same-name directory is preserved and installation stops; review and move that
+directory aside before retrying. Keep your custom content in the saved copy.
+
+Legacy `fnos` and `trim-cli` Skill directories are removed only when their
+ownership marker and digest manifest can also be verified. Historical installs
+without a marker are preserved with a warning, even if their names look familiar.
+Review those directories manually to avoid duplicate Skill instructions. Normal
+publication failures restore the original directories; if an interrupted process
+leaves an installation lock or a hidden backup, confirm no installer is running
+and review the retained files before retrying. The installer does not take over
+an existing lock automatically.
+
+Remove only the global command with:
+
+```bash
+npm uninstall --global @fnnas-labs/fnos-cli
+```
+
+This does not remove installed Skills, legacy directories, custom files or saved
+sessions. A user-scoped Skill is at `~/.agents/skills/fnos-cli`; a project-scoped
+Skill is at `.agents/skills/fnos-cli` inside that project. To remove a Skill,
+review that exact directory and back up any custom files before deleting it
+manually. Do not delete adjacent `fnos` or `trim-cli` directories without checking
+their contents.
+
+## Network and Private Registries
+
+Package installation requires access to an npm registry. To use an internal
+registry, provide it through npm configuration:
+
+```bash
+npm_config_registry=https://<npm-registry>/ npx -y --package=@fnnas-labs/fnos-cli@0.2.0 fnos-cli install
+```
+
+An HTTP 404 from the registry means the requested version is unavailable or the
+current npm account does not have permission to read it.
+
+## Verify the Version
+
+```bash
+fnos-cli --version
+trim-cli --version
+```
+
+Both commands should report the same version. Command behavior and detailed API
+documentation are installed with the Skill under
+`~/.agents/skills/fnos-cli/reference/`.
+
+## License
+
+The distributed fnOS CLI binaries, Skill documentation and integration code use
+the [MIT License](LICENSE). Copyright (c) 2026 Guangzhou TR Intelligent
+Manufacturing Technology Co., Ltd. Third-party components retain their respective
+licenses and notices, collected in [Third-party notices](THIRD_PARTY_NOTICES.txt).
+
+This license does not cover the fnOS operating system or server-side services.
+API access requires authorization and remains subject to the applicable service
+terms. The native CLI source is not included in the public Skill repository.