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

package/npm/package-lib.cjs

@@ -0,0 +1,274 @@
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { createHash } = require("node:crypto");
+
+const runtimePackageJson = JSON.parse(
+  fs.readFileSync(path.resolve(__dirname, "..", "package.json"), "utf8")
+);
+const PACKAGE_NAME = runtimePackageJson.name;
+const SKILL_NAME = runtimePackageJson.trimCliSkillName;
+const PRIMARY_COMMAND = runtimePackageJson.cliPrimaryCommand || "trim-cli";
+const OWNERSHIP_FILE = ".fnos-cli-ownership.json";
+if (runtimePackageJson.bin?.[PRIMARY_COMMAND] !== "npm/run.cjs") {
+  throw new Error(`Package does not expose the primary command ${PRIMARY_COMMAND}`);
+}
+const PLATFORM_BINARIES = Object.freeze({
+  "darwin-arm64": "trim-cli-darwin-arm64",
+  "darwin-x64": "trim-cli-darwin-x64",
+  "linux-arm64": "trim-cli-linux-arm64",
+  "linux-x64": "trim-cli-linux-x64",
+  "windows-arm64": "trim-cli-windows-arm64.exe",
+  "windows-x64": "trim-cli-windows-x64.exe"
+});
+
+function platformKey(platform = process.platform, arch = process.arch) {
+  const platformName = {
+    darwin: "darwin",
+    linux: "linux",
+    win32: "windows"
+  }[platform];
+  const archName = {
+    arm64: "arm64",
+    x64: "x64"
+  }[arch];
+
+  if (!platformName || !archName) {
+    throw new Error(`Unsupported platform: ${platform}-${arch}`);
+  }
+  return `${platformName}-${archName}`;
+}
+
+function packagedSkillRoot(packageRoot, options = {}) {
+  if (options.skillRoot) return options.skillRoot;
+  const skillName = options.expectedSkillName || SKILL_NAME;
+  const packaged = path.join(packageRoot, "skill");
+  if (fs.existsSync(path.join(packaged, "SKILL.md"))) return packaged;
+  return path.join(packaged, skillName === "fnos-cli" ? "fnos" : skillName);
+}
+
+function readJson(filePath, label) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (error) {
+    throw new Error(`Cannot read ${label} at ${filePath}: ${error.message}`);
+  }
+}
+
+function resolvePackagedBinary(packageRoot, platform, arch) {
+  const key = platformKey(platform, arch);
+  const binaryName = PLATFORM_BINARIES[key];
+  const binaryPath = path.join(packagedSkillRoot(packageRoot), "bin", binaryName);
+  if (!fs.existsSync(binaryPath)) {
+    throw new Error(`Package is missing the ${key} binary: ${binaryPath}`);
+  }
+  return binaryPath;
+}
+
+function validatePackagedSkill(packageRoot, options = {}) {
+  const packageJson = readJson(path.join(packageRoot, "package.json"), "package.json");
+  const expectedPackageName = options.expectedPackageName || PACKAGE_NAME;
+  const expectedSkillName = options.expectedSkillName || SKILL_NAME;
+  if (packageJson.name !== expectedPackageName) {
+    throw new Error(`Expected package name ${expectedPackageName}, got ${packageJson.name || "<missing>"}`);
+  }
+
+  const skillRoot = packagedSkillRoot(packageRoot, options);
+  const skillEntry = path.join(skillRoot, "SKILL.md");
+  if (!fs.existsSync(skillEntry)) {
+    throw new Error(`Package is missing the Skill entry: ${skillEntry}`);
+  }
+
+  const manifest = readJson(path.join(skillRoot, "manifest.json"), "Skill manifest");
+  if (manifest.name !== expectedSkillName) {
+    throw new Error(`Expected Skill name ${expectedSkillName}, got ${manifest.name || "<missing>"}`);
+  }
+  if (manifest.version !== packageJson.version) {
+    throw new Error(
+      `Package version ${packageJson.version} does not match Skill version ${manifest.version || "<missing>"}`
+    );
+  }
+
+  const requiredKeys = options.requireAllPlatforms
+    ? Object.keys(PLATFORM_BINARIES)
+    : [platformKey(options.platform, options.arch)];
+  for (const key of requiredKeys) {
+    const expectedRelativePath = `bin/${PLATFORM_BINARIES[key]}`;
+    if (!manifest.bin || manifest.bin[key] !== expectedRelativePath) {
+      throw new Error(`Skill manifest does not map ${key} to ${expectedRelativePath}`);
+    }
+    const binaryPath = path.join(skillRoot, expectedRelativePath);
+    if (!fs.existsSync(binaryPath)) {
+      throw new Error(`Skill is missing the ${key} binary: ${binaryPath}`);
+    }
+  }
+
+  return { packageJson, manifest, skillRoot };
+}
+
+function resolveSkillDestination({ project = false, cwd = process.cwd(), homeDir = os.homedir() } = {}) {
+  const base = project ? cwd : homeDir;
+  return path.join(base, ".agents", "skills", SKILL_NAME);
+}
+
+// The full tree is recorded, including empty directories. A changed file,
+// additional user file or symlink makes the installation ineligible for removal.
+function skillDigests(root) {
+  const entries = Object.create(null);
+  if (!fs.lstatSync(root).isDirectory()) throw new Error(`Skill is not a directory: ${root}`);
+  function visit(directory, prefix = "") {
+    for (const name of fs.readdirSync(directory).sort()) {
+      if (!prefix && name === OWNERSHIP_FILE) continue;
+      const relative = prefix ? `${prefix}/${name}` : name;
+      const absolute = path.join(directory, name);
+      const stat = fs.lstatSync(absolute);
+      if (stat.isDirectory()) {
+        entries[relative] = null;
+        visit(absolute, relative);
+      } else if (stat.isFile()) {
+        entries[relative] = createHash("sha256").update(fs.readFileSync(absolute)).digest("hex");
+      } else {
+        throw new Error(`Skill contains a symlink or unsupported file: ${absolute}`);
+      }
+    }
+  }
+  visit(root);
+  return entries;
+}
+
+function verifiedOwnership(root) {
+  try {
+    const markerPath = path.join(root, OWNERSHIP_FILE);
+    if (!fs.lstatSync(markerPath).isFile()) return false;
+    const marker = readJson(markerPath, "Skill ownership marker");
+    const knownPackage = marker.package === PACKAGE_NAME
+      || (SKILL_NAME === "fnos-cli" && marker.package === "@trimjs/trim-cli");
+    const knownSkill = marker.skill === SKILL_NAME
+      || (SKILL_NAME === "fnos-cli" && ["fnos", "trim-cli"].includes(marker.skill));
+    if (marker.schema !== 1 || !knownPackage || !knownSkill
+      || typeof marker.version !== "string" || !marker.version
+      || !marker.entries || typeof marker.entries !== "object" || Array.isArray(marker.entries)) return false;
+    const actual = skillDigests(root);
+    const names = Object.keys(actual);
+    return names.length > 0 && names.length === Object.keys(marker.entries).length
+      && names.every((name) => Object.hasOwn(marker.entries, name) && marker.entries[name] === actual[name]);
+  } catch (_) {
+    return false;
+  }
+}
+
+function writeOwnership(root) {
+  if (fs.existsSync(path.join(root, OWNERSHIP_FILE))) {
+    throw new Error("Packaged Skill unexpectedly contains an installation ownership marker");
+  }
+  const marker = {
+    schema: 1, package: PACKAGE_NAME, skill: SKILL_NAME,
+    version: runtimePackageJson.version, entries: skillDigests(root)
+  };
+  fs.writeFileSync(path.join(root, OWNERSHIP_FILE), `${JSON.stringify(marker, null, 2)}\n`, { flag: "wx" });
+}
+
+function pathExists(file) {
+  try { fs.lstatSync(file); return true; }
+  catch (error) { if (error.code === "ENOENT") return false; throw error; }
+}
+
+function copySkillAtomically(source, destination) {
+  const parent = path.dirname(destination);
+  fs.mkdirSync(parent, { recursive: true });
+
+  const nonce = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  const lockPath = path.join(parent, `.${SKILL_NAME}.install.lock`);
+  const stagingPath = path.join(parent, `.${SKILL_NAME}.install-${nonce}`);
+  let lockHandle;
+  const moved = [];
+  const warnings = [];
+
+  try {
+    try {
+      lockHandle = fs.openSync(lockPath, "wx", 0o600);
+    } catch (error) {
+      if (error.code === "EEXIST") {
+        throw new Error(`Another ${SKILL_NAME} installation is already running: ${lockPath}`);
+      }
+      throw error;
+    }
+
+    fs.cpSync(source, stagingPath, { recursive: true, errorOnExist: true });
+    if (!fs.existsSync(path.join(stagingPath, "SKILL.md"))) {
+      throw new Error(`Staged Skill is missing SKILL.md: ${stagingPath}`);
+    }
+    writeOwnership(stagingPath);
+
+    if (pathExists(destination)) {
+      if (!verifiedOwnership(destination)) {
+        throw new Error(`Cannot verify ownership of existing Skill; preserved without changes: ${destination}. Move it aside after reviewing your files, then retry.`);
+      }
+    }
+
+    // An unmarked historical installation cannot be distinguished from a user's
+    // own Skill. Never infer ownership from a familiar name or SKILL.md alone.
+    const legacy = SKILL_NAME === "fnos-cli" ? ["fnos", "trim-cli"] : [];
+    const candidates = [];
+    for (const name of legacy) {
+      const old = path.join(parent, name);
+      if (!pathExists(old)) continue;
+      if (verifiedOwnership(old)) candidates.push(old);
+      else warnings.push(`Cannot verify ownership; preserved legacy Skill: ${old}. Review it manually before removing it.`);
+    }
+    if (pathExists(destination)) candidates.push(destination);
+    for (const original of candidates) {
+      // Recheck after staging so edits made during a slow copy stay protected.
+      if (!verifiedOwnership(original)) throw new Error(`Skill ownership changed during installation; preserved: ${original}`);
+      const backup = path.join(parent, `.${SKILL_NAME}.backup-${nonce}-${path.basename(original)}`);
+      fs.renameSync(original, backup);
+      moved.push({ original, backup });
+    }
+    fs.renameSync(stagingPath, destination);
+  } catch (error) {
+    try { fs.rmSync(stagingPath, { recursive: true, force: true }); }
+    catch (cleanupError) { error.message += `; staging cleanup requires review at ${stagingPath}: ${cleanupError.message}`; }
+    for (const { original, backup } of moved.reverse()) {
+      try {
+        if (!pathExists(original) && pathExists(backup)) fs.renameSync(backup, original);
+        else error.message += `; restore requires review: ${backup} -> ${original}`;
+      } catch (restoreError) {
+        error.message += `; original data retained at ${backup}: ${restoreError.message}`;
+      }
+    }
+    throw error;
+  } finally {
+    if (lockHandle !== undefined) {
+      fs.closeSync(lockHandle);
+      fs.rmSync(lockPath, { force: true });
+    }
+  }
+
+  // Publication succeeded. Cleanup failures must not pretend the old tree can
+  // still be rolled back after some owned backups have already been removed.
+  for (const { backup } of moved) {
+    try {
+      if (!verifiedOwnership(backup)) {
+        warnings.push(`Backup ownership changed; preserved for review: ${backup}`);
+        continue;
+      }
+      fs.rmSync(backup, { recursive: true, force: true });
+    }
+    catch (error) { warnings.push(`Installed Skill, but could not remove owned backup ${backup}: ${error.message}`); }
+  }
+  return warnings;
+}
+
+module.exports = {
+  PACKAGE_NAME,
+  PRIMARY_COMMAND,
+  PLATFORM_BINARIES,
+  SKILL_NAME,
+  copySkillAtomically,
+  packagedSkillRoot,
+  platformKey,
+  readJson,
+  resolvePackagedBinary,
+  resolveSkillDestination,
+  validatePackagedSkill
+};

package/npm/run.cjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+const { spawn } = require("node:child_process");
+const path = require("node:path");
+const { main: install } = require("./install.cjs");
+const { PRIMARY_COMMAND, resolvePackagedBinary } = require("./package-lib.cjs");
+const packageJson = require("../package.json");
+
+const args = process.argv.slice(2);
+if (args.length === 1 && (args[0] === "--version" || args[0] === "-V")) {
+  console.log(`${PRIMARY_COMMAND} ${packageJson.version}`);
+} else if (args[0] === "install") {
+  try {
+    install(args.slice(1));
+  } catch (error) {
+    console.error(`${PRIMARY_COMMAND} install failed: ${error.message}`);
+    process.exitCode = 1;
+  }
+} else {
+  try {
+    const packageRoot = path.resolve(__dirname, "..");
+    const binary = resolvePackagedBinary(packageRoot);
+    const child = spawn(binary, args, { stdio: "inherit", windowsHide: true });
+    child.once("error", (error) => {
+      console.error(`Cannot start ${PRIMARY_COMMAND}: ${error.message}`);
+      process.exitCode = 1;
+    });
+    child.once("exit", (code, signal) => {
+      if (signal && process.platform !== "win32") {
+        process.kill(process.pid, signal);
+      } else {
+        process.exitCode = code === null ? 1 : code;
+      }
+    });
+  } catch (error) {
+    console.error(`Cannot start ${PRIMARY_COMMAND}: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@fnnas-labs/fnos-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "fnOS CLI and Agent Skill",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fnnas-labs/fnos-cli-skill.git"
+  },
+  "trimCliSkillName": "fnos-cli",
+  "cliPrimaryCommand": "fnos-cli",
+  "main": "npm/dsh.mjs",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "license": "MIT",
+  "bin": {
+    "fnos-cli": "npm/run.cjs",
+    "trim-cli": "npm/run.cjs"
+  },
+  "files": [
+    "npm/*.cjs",
+    "skill/**",
+    "npm/dsh.mjs",
+    "npm/dsh-integration.mjs",
+    "npm/dsh-test-support.mjs",
+    "npm/acceptance-report.cjs",
+    "npm/README.dsh.md",
+    "cordis.patch.yml",
+    "THIRD_PARTY_NOTICES.txt"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skill/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/skill/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: fnos-cli
+description: Use fnos-cli to sign in to and manage fnOS devices, including files, photos, applications, Docker, downloads, logs, monitoring, networking, storage, users, and Baidu Netdisk. Use when the user mentions fnOS, Feiniu OS, or a mainland China device. Excludes Media APIs and international-edition devices.
+---
+
+# fnOS
+
+The command-line client for fnOS. It uses the HTTP API proxy for
+system services and native applications: authentication, files, photos, apps,
+Docker, downloads, logs, monitoring, networking, power, storage, and users.
+
+Examples assume `fnos-cli` is available on PATH. An integration may provide
+an explicit package-local launcher instead; follow that integration's instructions.
+
+## Standalone bundle launcher
+
+For a standalone Skill bundle containing `scripts/`, use the absolute path to
+`scripts/fnos-cli` (macOS/Linux) or `scripts/fnos-cli.cmd` (Windows)
+inside this Skill's directory. Resolve it from the loaded Skill location, not the
+working directory. Check `--version` before device operations.
+
+## Task routing
+
+Choose the most specific entry, then follow its reference or workflow. For a
+product-specific task not listed below, inspect the descriptions in `entries/`.
+
+| Task | Entry |
+| --- | --- |
+| Sign in, sessions, connection failures, profiles | `entries/trim-shared.md`, `reference/_index.md` |
+| Files, finder, shares, ACLs, uploads and downloads | `entries/trim-file.md`, `reference/workflows/file-routing.md` |
+| Photo search, AI search, details and previews | `entries/trim-photos.md`, `reference/workflows/photos-routing.md` |
+| Apps, Docker, downloads, logs and monitoring | Matching file in `entries/`, `reference/_index.md` |
+| Storage writes | `entries/trim-storage.md`, `reference/workflows/storage-dangerous-ops.md` |
+| Users, groups and permissions | `entries/trim-user.md`, `reference/user.md` |
+| Device validation | `reference/workflows/device-validation.md` |
+
+## Safety rules
+
+- Media APIs are outside this Skill's scope; use the documented capabilities only.
+- Authentication uses OAuth 2.0 Authorization Code + PKCE. The user handles NAS
+  credentials and 2FA in their browser; never collect passwords or old tokens.
+- OAuth uses `client_id=YJNMPJUGA9` and the CLI's required `trim.*` scopes. See
+  `reference/oauth.md` for the full list. Authorization URLs omit `redirect_uri`.
+- Production login is interactive: the CLI displays a link and waits while the
+  user signs in, approves access, copies the one-time code, and pastes it into the
+  CLI's `Authorization code` prompt. The Agent does not fill credentials, approve
+  access, read browser codes, or pass codes in command arguments.
+- Run login in the actual execution environment. DSH requires the same Host,
+  system user, configuration environment and profile as the user's login terminal.
+  Remote browsers, SSH shells and containers do not automatically share sessions.
+- Sessions hold access/refresh tokens, expiry and OAuth device information. Store
+  secrets only in platform secure storage or an explicitly selected file backend;
+  keep them out of ordinary output, logs and third-party messages.
+- Tokens refresh near expiry. HTTP 401 from `/ogh/ac/w` or `/ogh/ac/h/*` triggers
+  one refresh and one retry. Repeated 401 or refresh failure requires a new OAuth
+  login, not a retry loop or a legacy authentication fallback.
+- Refresh first checks that the profile's session store is writable. Concurrent
+  refreshes reuse an already-written newer token.
+- Missing module scopes, including legacy `file photo` grants, require login
+  again; refresh cannot add scopes.
+- `logout` removes the profile's session and OAuth pending file. It does not
+  claim to revoke server-side tokens.
+- Remote plain HTTP requires `--allow-insecure-http`; self-signed HTTPS requires
+  `--tls-insecure`.
+- Agent and noninteractive writes explicitly pass `--yes`. High-risk storage
+  writes also require the relevant password precheck.
+
+## Connection options
+
+```text
+--host <host>                 NAS host; defaults to localhost
+--port <port>                 Explicit port takes precedence
+--profile <name>              Independent session profile
+--scheme auto|http|https      Transport; defaults to auto
+--allow-insecure-http         Allow remote plain HTTP
+--tls-insecure                Allow self-signed HTTPS
+```
+
+Without explicit connection options, the CLI reuses the profile's saved host,
+port, scheme and TLS settings. Defaults are `http://localhost:5666` for loopback,
+HTTPS 5667 for remote IPs, and HTTPS 443 for domain names.
+
+## Authentication
+
+The user runs these commands in their own interactive terminal:
+
+```bash
+fnos-cli --profile home --host <host> --port <port> --scheme https login
+fnos-cli --profile home login --refresh
+fnos-cli --profile home logout
+```
+
+`login` displays the authorization link, attempts to open a browser, and waits
+for the user to paste a one-time code. `login --no-open` keeps the same flow
+without opening the browser automatically. For a remote plain HTTP device:
+
+```bash
+fnos-cli --profile home --host <host> --port 5666 --scheme http --allow-insecure-http login --no-open
+```
+
+## Common read-only commands
+
+```bash
+fnos-cli --profile home system info
+fnos-cli --profile home file ls /vol1
+fnos-cli --profile home file ls-dir /vol1
+fnos-cli --profile home file usage 1
+fnos-cli --profile home photos folders
+fnos-cli --profile home photos search <keyword> --limit 20
+fnos-cli --profile home app list
+fnos-cli --profile home docker image ls
+fnos-cli --profile home download ls
+fnos-cli --profile home monitor cpu
+fnos-cli --profile home monitor beep-supported
+fnos-cli --profile home storage pools
+fnos-cli --profile home user info
+```
+
+## Raw requests
+
+Use `raw` for system services without a named command, and `photos request` for
+the native Photos HTTP API. Only audited read-only endpoints built into the CLI
+may omit `--yes`; every other endpoint, including unknown endpoints, requires
+confirmation and explicit `--yes`. Paths and request bodies are still validated.
+Check both HTTP status and business response code/final state, not just exit code.
+
+## Output
+
+Named commands output JSON plans or business data. Photos search `total` is the
+match count. AI search may report an exact total only when the response provides
+a stable total; otherwise report the returned count. Preview URLs usually still
+require a signed-in browser cookie.
+
+`file ls-dir` collects directory chunks into a JSON array. `file usage` collects
+capacity categories into a JSON array; repeated categories keep their last
+result instead of being added together.
+
+## References
+
+- Index: `reference/_index.md`
+- OAuth contract: `reference/oauth.md`
+- Photos API: `reference/photos.md`
+- Connections and validation: `entries/trim-shared.md`, `reference/workflows/device-validation.md`