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

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: fnos-cli
+      name: '@fnnas-labs/fnos-cli'

package/npm/README.dsh.md

@@ -0,0 +1,49 @@
+# fnOS CLI for DSH
+
+The `@fnnas-labs/fnos-cli` package includes its native CLI, matching Skill, and a DSH bundle. The bundle activates `npm/dsh.mjs`, which explicitly registers `fnos-cli` with the Skill service. Installing a bundle and registering a Skill are separate steps.
+
+Install the package into the DSH profile you use, for example:
+
+```sh
+dsh plugin --profile headless add @fnnas-labs/fnos-cli@0.2.1
+```
+
+The Skill derives `../npm/run.cjs` from its resource directory and instructs the Agent to call that launcher through Node. Global `fnos-cli` and `trim-cli` commands are not required. The adapter loads only local packaged documents; it does not execute commands, add write confirmation flags, or log in.
+
+For first login, the user runs this in a real terminal on the CLI execution host:
+
+```sh
+npx -y --package=@fnnas-labs/fnos-cli@0.2.1 fnos-cli login --profile <profile> --host <nas-host> --port <port>
+```
+
+Replace the NAS host/port with the user's chosen endpoint; ask when unknown rather than assuming localhost. For an existing profile, omit these options to reuse its saved endpoint unless changing devices. The terminal and DSH invocation must use the same DSH Host, system user, configuration environment and profile. The user completes browser authorization and enters the code in that terminal. Default one-shot DSH shells have no interactive login TTY. Remote browsers, SSH providers and containers do not automatically share the host's installation or session. macOS Keychain access may require system approval.
+
+## Deterministic integration check
+
+DSH acceptance is run manually by the user, not on every CI run. Choose when to
+run these checks against a frozen candidate. Successful runners save a private
+`report.json` with an `acceptance` receipt containing the package identity,
+tarball SHA-256, runtime and coverage limits. A receipt for a different tarball
+cannot validate a rebuilt package, even when the version is unchanged.
+
+With Node.js, npm, pnpm and a DSH-supported macOS/Linux shell, run against an actual staged npm tarball:
+
+```sh
+node npm/dsh-integration.mjs --tarball /absolute/path/fnnas-labs-fnos-cli-0.2.1.tgz
+```
+
+The runner pins DSH to `0.2.0-rc.2`, installs the tarball in a fresh DSH Home, and runs the real headless Agent's `skill` and `bash` tools using a local **scripted model**. No provider key, NAS or OAuth is required. It verifies Skill discovery, a resource-derived same-package launcher, native help, a fake-profile read-only connection attempt and refusal of an unconfirmed write. The shell PATH contains Node only; installation paths include spaces and an apostrophe. Logs and isolated configuration remain under `.tmp/` for inspection. An explicit `FNOS_DSH_CLI` can select an already installed DSH CLI entry; `FNOS_DSH_NPM_CACHE` and `FNOS_DSH_PNPM_STORE` can reuse dependency caches. These options do not change the isolated DSH Home or CLI session directory.
+
+This check proves the tool chain, not autonomous Skill selection by a real model, successful NAS authorization, Keychain background access or Windows behavior. Linux/Windows manual checks and real-model acceptance are separate. The existing shell path is used first; a dedicated argv tool should only be added if platform acceptance demonstrates a need.
+
+## Opt-in macOS device acceptance (source checkout)
+
+After the user completes OAuth in a real terminal, maintainers can run the separate source-checkout runner against a reviewed candidate tarball:
+
+```sh
+node npm/dsh-device-acceptance.mjs --tarball /absolute/path/fnnas-labs-fnos-cli-0.2.1.tgz --profile <existing-profile> --use-existing-session
+```
+
+Add `--allow-insecure-http` only when the authorized device uses plaintext HTTP. The runner preserves the invoking user's HOME, CLI configuration environment and secure session storage; it creates only a fresh DSH Home/workspace. File/ask-file storage and profiles with an existing legacy file fallback are rejected (files are left unchanged and unread). It never performs login, receives OAuth codes or requests passwords. The scripted model directs the real Skill and shell tools to package-local native help, system info, current-user info and a repeated read-only request. The PATH retains macOS system utilities for Keychain access, while explicitly checking that neither global CLI name resolves.
+
+Reports identify the candidate tarball hash and the scripted-model limitation. Device output stays in private `.tmp/` logs; the summary includes output hashes, not device payloads. A passing run confirms existing-session reuse from a background DSH process, not the manual first-login ceremony, natural-expiry refresh, autonomous real-model selection, Linux/Windows, npm registry or Market installation. This runner is opt-in and is not run by default CI or shipped as a consumer command.

package/npm/acceptance-report.cjs

@@ -0,0 +1,53 @@
+// Shared receipt for local, opt-in acceptance runners. No registry or device calls.
+const fs = require("node:fs");
+const { createHash } = require("node:crypto");
+
+const KINDS = ["candidate-install", "dsh-scripted", "dsh-device", "public-bridge"];
+const nonempty = (value) => typeof value === "string" && value.length > 0;
+const validArtifact = (value) => value && nonempty(value.name) && nonempty(value.version) && /^[a-f0-9]{64}$/.test(value.sha256);
+function sha256(file) {
+  return createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+
+function receipt({ tarball, name, version, kind, expectedSha256, notVerified = [], tools = {} }) {
+  if (!KINDS.includes(kind)) throw new Error(`Unknown acceptance kind: ${kind}`);
+  if (!nonempty(name) || !nonempty(version)) throw new Error("Acceptance requires package name and version");
+  const digest = sha256(tarball);
+  if (!expectedSha256 || digest !== expectedSha256) throw new Error("Tarball changed during acceptance; rerun against an immutable candidate");
+  return {
+    schema: 1, kind, result: "PASS", checkedAt: new Date().toISOString(),
+    artifact: { name, version, sha256: digest },
+    environment: { platform: process.platform, arch: process.arch, node: process.version, tools },
+    notVerified,
+  };
+}
+
+function collect(artifact, reports) {
+  if (!validArtifact(artifact)) throw new Error("Invalid candidate artifact identity");
+  if (!reports.length) throw new Error("Provide at least one acceptance report");
+  const receipts = reports.map((report) => {
+    const entry = report?.acceptance;
+    if (entry?.schema !== 1 || !KINDS.includes(entry.kind) || entry.result !== "PASS"
+      || !validArtifact(entry.artifact)
+      || !Array.isArray(entry.notVerified) || !entry.notVerified.every(nonempty)
+      || !["platform", "arch", "node"].every((key) => nonempty(entry.environment?.[key]))
+      || !nonempty(entry.checkedAt) || !Number.isFinite(Date.parse(entry.checkedAt))
+      || (report.result !== undefined && report.result !== "PASS")
+      || (report.results !== undefined && report.results !== "PASS")) {
+      throw new Error("Invalid or legacy acceptance report; rerun the relevant check manually");
+    }
+    if (["name", "version", "sha256"].some((key) => artifact[key] !== entry.artifact?.[key])) {
+      throw new Error("Acceptance report belongs to a different tarball (name/version/SHA256)");
+    }
+    return entry;
+  });
+  return {
+    schema: 1, artifact, receipts,
+    missing: KINDS.filter((kind) => !receipts.some((entry) => entry.kind === kind)),
+    notVerified: [...new Set(receipts.flatMap((entry) => entry.notVerified))],
+    // Deliberately no overall PASS: collecting evidence does not approve a release.
+    approval: "manual review required; DSH acceptance is user-run, not a CI gate",
+  };
+}
+
+module.exports = { KINDS, sha256, receipt, collect };

package/npm/dsh-integration.mjs

@@ -0,0 +1,159 @@
+// Deterministic integration check: scripted model, real DSH Agent and shell tools.
+// This is not evidence that a real model selects the Skill autonomously.
+import assert from 'node:assert/strict'
+import { createServer } from 'node:http'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, symlinkSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createDshRunner, quote, sendMessage, stringsInside } from './dsh-test-support.mjs'
+import acceptance from './acceptance-report.cjs'
+
+const repository = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const args = process.argv.slice(2)
+assert.equal(args.length, 2, 'Usage: node npm/dsh-integration.mjs --tarball /absolute/path/package.tgz')
+assert.equal(args[0], '--tarball')
+assert.notEqual(process.platform, 'win32', 'This Bash integration runner requires macOS/Linux; Windows acceptance is separate.')
+const tarball = resolve(args[1])
+assert.ok(existsSync(tarball), `Tarball does not exist: ${tarball}`)
+const tarballSha256 = acceptance.sha256(tarball)
+mkdirSync(join(repository, '.tmp'), { recursive: true })
+// Spaces and an apostrophe exercise installation-path quoting as well as argv.
+const scratch = mkdtempSync(join(repository, '.tmp', "fnos dsh 'integration-"))
+const workspace = join(scratch, 'workspace')
+const dshHome = join(scratch, 'home')
+const nodeBin = join(scratch, 'node-only-path')
+mkdirSync(workspace)
+mkdirSync(nodeBin)
+symlinkSync(process.execPath, join(nodeBin, 'node'))
+mkdirSync(join(scratch, 'session', 'profiles'), { recursive: true })
+writeFileSync(join(scratch, 'session', 'profiles', 'integration.json'), JSON.stringify({
+  host: '127.0.0.1', port: 1, username: 'integration', uid: 1, admin: false,
+  accessToken: 'integration-not-a-real-token', oauthClientId: 'YJNMPJUGA9',
+  oauthScope: 'trim.user.all trim.file.read trim.file.write trim.download.all trim.appcenter.all trim.photo.all trim.baidu_netdisk.all trim.system.all trim.log.all trim.storage.all trim.docker.all', updatedAt: '2026-10-09T00:00:00Z',
+}), { mode: 0o600 })
+const env = {
+  ...process.env, DSH_HOME: dshHome,
+  TRIM_CLI_CONFIG_DIR: join(scratch, 'session'), TRIM_CLI_SESSION_STORAGE: 'file',
+  DSH_TELEMETRY_MODE: 'DISABLED', DSH_TELEMETRY_DISABLED: '1',
+  DSH_PERMISSION_MODE: 'workspace-write',
+  npm_config_cache: process.env.FNOS_DSH_NPM_CACHE || join(scratch, 'npm-cache'),
+}
+const runDsh = createDshRunner({ workspace, env, scratch })
+
+// A bridge test changes only this isolated profile's dependency resolution.
+// The generated public bridge keeps its exact registry-version dependency.
+const bridgeTarball = process.env.FNOS_DSH_BRIDGE_TARBALL && resolve(process.env.FNOS_DSH_BRIDGE_TARBALL)
+if (bridgeTarball) {
+  assert.ok(existsSync(bridgeTarball))
+  const profileDirectory = join(dshHome, 'profiles', 'headless')
+  mkdirSync(profileDirectory, { recursive: true })
+  writeFileSync(join(profileDirectory, 'package.json'), JSON.stringify({
+    name: 'dsh-profile-headless', private: true, dependencies: {},
+    dsh: { profile: { bundles: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-headless'] } },
+  }, null, 2))
+  writeFileSync(join(profileDirectory, 'pnpm-workspace.yaml'),
+    `packages:\n  - .\nnodeLinker: hoisted\nautoInstallPeers: false\noverrides:\n  '@fnnas-labs/fnos-cli': ${JSON.stringify(`file:${tarball}`)}\n`)
+}
+const installArgs = ['plugin', '--profile', 'headless', 'add', bridgeTarball || tarball]
+if (process.env.FNOS_DSH_PNPM_STORE) installArgs.push('--store-dir', resolve(process.env.FNOS_DSH_PNPM_STORE))
+console.log(`DSH integration scratch: ${scratch}`)
+const dshVersion = (await runDsh(['--version'])).trim()
+assert.equal(dshVersion, '0.2.0-rc.2', 'Integration acceptance is pinned to the verified DSH version')
+await runDsh(installArgs)
+const installed = join(dshHome, 'profiles', 'headless', 'node_modules', '@fnnas-labs', 'fnos-cli')
+const metadata = JSON.parse(readFileSync(join(installed, 'package.json'), 'utf8'))
+const manifest = JSON.parse(readFileSync(join(installed, 'skill', 'manifest.json'), 'utf8'))
+assert.equal(metadata.name, '@fnnas-labs/fnos-cli')
+assert.equal(manifest.name, 'fnos-cli')
+assert.equal(manifest.version, metadata.version, 'CLI and Skill must ship in the same versioned package')
+const expectedVersion = `fnos-cli ${metadata.version}`
+const expectedLauncher = join(installed, 'npm', 'run.cjs')
+const steps = [
+  { name: 'skill', input: { name: 'fnos-cli' }, label: 'skill' },
+  { name: 'bash', label: 'no-global-cli', input: { command: `PATH=${quote(nodeBin)}; export PATH; command -v fnos-cli; command -v trim-cli`, description: 'Verify no global CLI is accessible' } },
+  { name: 'bash', label: 'version', input: { description: 'Read the package-local CLI version' } },
+  { name: 'bash', label: 'help', input: { description: 'Read native CLI help' } },
+  { name: 'bash', label: 'write-confirmation', input: { description: 'Verify an unconfirmed write is rejected without connecting' } },
+  { name: 'bash', label: 'read-only-session', input: { description: 'Check the isolated fake profile with a read-only command' } },
+]
+const observations = []
+let stepIndex = 0
+let serverError
+
+function launcherFromSkill(messages) {
+  const content = stringsInside(messages).find(value => value.includes('Base directory for this skill: '))
+  const base = /Base directory for this skill: ([^\n]+)/.exec(content || '')?.[1]
+  assert.ok(base, 'DSH Skill tool must return a resource directory')
+  assert.match(content, /DSH package-local invocation/, 'Skill must explain its package-local entry')
+  assert.match(content, /\.\.\/npm\/run\.cjs/)
+  assert.match(content, /same (?:system )?user/)
+  assert.match(content, /npx -y --package=@fnnas-labs\/fnos-cli@[^ ]+ fnos-cli login/)
+  assert.match(content, /--host <nas-host> --port <port>/, 'First login must identify the user-selected NAS endpoint')
+  assert.match(content, /--yes/)
+  const launcher = resolve(base, '../npm/run.cjs')
+  assert.equal(launcher, expectedLauncher, 'Derive the same-package launcher from Skill output, not a preseeded command')
+  return launcher
+}
+
+const server = createServer(async (request, response) => {
+  try {
+    assert.equal(request.method, 'POST')
+    assert.equal(request.url, '/v1/messages')
+    const chunks = []
+    for await (const chunk of request) chunks.push(chunk)
+    const body = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+    const step = body.tools?.length ? steps[stepIndex] : null
+    if (step) {
+      assert.ok(body.tools.some(tool => tool.name === step.name), `DSH must advertise ${step.name}`)
+      if (stepIndex === 0) {
+        assert.match(JSON.stringify(body), /<available_skills>[\s\S]*fnos-cli/, 'DSH must expose fnos-cli in the model-facing Skill catalog')
+      }
+      if (stepIndex >= 2) {
+        const launcher = launcherFromSkill(body.messages)
+        const commands = {
+          version: '--version', help: '--help',
+          'write-confirmation': `--profile integration file rename ${quote('/vol1/1/a file;$(echo forbidden)')} ${quote("new 'name'")}`,
+          'read-only-session': '--profile integration system info',
+        }
+        step.input.command = `PATH=${quote(nodeBin)}; export PATH; node ${quote(launcher)} ${commands[step.label]}`
+      }
+      observations.push({ label: step.label, tool: step.name })
+    }
+    sendMessage(response, step, stepIndex)
+    if (step) stepIndex += 1
+  } catch (error) {
+    serverError = error
+    sendMessage(response, null, stepIndex)
+  }
+})
+await new Promise(ready => server.listen(0, '127.0.0.1', ready))
+env.DEEPSEEK_BASE_URL = `http://127.0.0.1:${server.address().port}`
+env.DEEPSEEK_API_KEY = 'scripted-local-model-not-a-secret'
+let stdout
+try {
+  stdout = await runDsh(['headless', '--json', 'Load the fnOS Skill and check its package-local CLI.'])
+} finally {
+  await new Promise(done => server.close(done))
+}
+if (serverError) throw serverError
+const events = stdout.split('\n').flatMap(line => { try { return [JSON.parse(line)] } catch { return [] } })
+const results = events.filter(event => event.type === 'tool_result')
+assert.equal(results.length, steps.length, 'Every scripted command must reach a real DSH tool result')
+assert.ok(results.every(result => result.status === 'completed'), 'Every tool must execute rather than return a tool-layer error')
+const outputs = results.map(result => JSON.stringify(result))
+assert.match(outputs[0], /DSH package-local invocation/)
+assert.equal(results[1].result, '(no output)\n[exit code: 1]', 'Neither CLI command may resolve on the isolated PATH')
+assert.ok(outputs[2].includes(expectedVersion), `Expected ${expectedVersion}`)
+assert.match(outputs[3], /Usage:/, 'Help must execute the native binary, not just the Node version shortcut')
+assert.match(outputs[4], /pass --yes to confirm/)
+assert.doesNotMatch(outputs[4], /failed to get file data/)
+assert.match(outputs[5], /failed to get system info from 127\.0\.0\.1:1/)
+const report = {
+  acceptance: acceptance.receipt({ tarball, name: metadata.name, version: metadata.version,
+    kind: 'dsh-scripted', expectedSha256: tarballSha256, tools: { dsh: dshVersion },
+    notVerified: ['real-model autonomous selection', 'OAuth/device acceptance', 'npm registry install', 'DSH Market install'] }),
+  model: 'scripted (not real-model acceptance)', dsh: dshVersion, version: metadata.version,
+  observations, results: 'PASS', scratch,
+}
+writeFileSync(join(scratch, 'report.json'), `${JSON.stringify(report, null, 2)}\n`, { mode: 0o600 })
+console.log(JSON.stringify(report, null, 2))

package/npm/dsh-test-support.mjs

@@ -0,0 +1,55 @@
+// Shared test harness only; the consumer DSH adapter does not import this file.
+import assert from 'node:assert/strict'
+import { spawn } from 'node:child_process'
+import { writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+export const quote = value => `'${value.replaceAll("'", "'\\''")}'`
+
+export function stringsInside(value) {
+  if (typeof value === 'string') return [value]
+  if (Array.isArray(value)) return value.flatMap(stringsInside)
+  return value && typeof value === 'object' ? Object.values(value).flatMap(stringsInside) : []
+}
+
+export function createDshRunner({ workspace, env, scratch }) {
+  const prefix = env.FNOS_DSH_CLI
+    ? { command: process.execPath, args: [resolve(env.FNOS_DSH_CLI)] }
+    : { command: 'npm', args: ['exec', '--yes', '--package=@deepseek-ai/dsh@0.2.0-rc.2', '--', 'dsh'] }
+  return async args => {
+    const child = spawn(prefix.command, [...prefix.args, ...args], { cwd: workspace, env, stdio: ['ignore', 'pipe', 'pipe'] })
+    let stdout = ''
+    let stderr = ''
+    child.stdout.on('data', data => { stdout += data })
+    child.stderr.on('data', data => { stderr += data })
+    const timer = setTimeout(() => child.kill('SIGTERM'), 180_000)
+    try {
+      const code = await new Promise((done, reject) => {
+        child.once('error', reject)
+        child.once('close', done)
+      })
+      assert.equal(code, 0, `DSH ${args[0]} failed (${code}); inspect private scratch logs: ${scratch}`)
+      return stdout
+    } finally {
+      clearTimeout(timer)
+      writeFileSync(join(scratch, `${args[0]}.stdout.log`), stdout, { mode: 0o600 })
+      writeFileSync(join(scratch, `${args[0]}.stderr.log`), stderr, { mode: 0o600 })
+    }
+  }
+}
+
+export function sendMessage(response, step, index) {
+  const events = [
+    { type: 'message_start', message: { id: `msg-${index}`, type: 'message', role: 'assistant', model: 'deepseek-chat', content: [], stop_reason: null, usage: { input_tokens: 10, output_tokens: 0 } } },
+    { type: 'content_block_start', index: 0, content_block: step
+      ? { type: 'tool_use', id: `call-${index}`, name: step.name, input: {} }
+      : { type: 'text', text: 'Scripted-model tool-chain check complete.' } },
+    ...(step ? [{ type: 'content_block_delta', index: 0, delta: { type: 'input_json_delta', partial_json: JSON.stringify(step.input) } }] : []),
+    { type: 'content_block_stop', index: 0 },
+    { type: 'message_delta', delta: { stop_reason: step ? 'tool_use' : 'end_turn' }, usage: { output_tokens: 10 } },
+    { type: 'message_stop' },
+  ]
+  response.writeHead(200, { 'content-type': 'text/event-stream' })
+  for (const event of events) response.write(`event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`)
+  response.end()
+}

package/npm/dsh.mjs

@@ -0,0 +1,31 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+export const name = 'fnos-cli'
+export const inject = ['skills']
+
+export function apply(ctx) {
+  const skillDirectory = new URL('../skill/', import.meta.url)
+  const metadata = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+  const markdown = readFileSync(new URL('SKILL.md', skillDirectory), 'utf8')
+  const body = markdown.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '').trim()
+  const invocation = `## DSH package-local invocation
+
+1. Resolve \`../npm/run.cjs\` against the base directory returned by this Skill. This is the launcher shipped with this Skill's npm package, version ${metadata.version}.
+2. In the local DSH Host shell, run \`node "<resolved-launcher>" <arguments>\`. Replace every \`fnos-cli\` or \`trim-cli\` command prefix in this Skill and its references with that invocation. Quote the resolved path and each argument for the active shell (Bash or PowerShell), including spaces, apostrophes and shell metacharacters. Keep each argument separate. The launcher's path is outside the workspace and does not require changing the working directory.
+3. Begin with \`--version\` or \`--help\`, then use the requested read-only command and the chosen \`--profile\`. This entry does not require a global CLI installation and never adds \`--yes\` for you. Only include \`--yes\` after the user explicitly authorizes the corresponding write.
+
+### First login or an expired session
+
+For a new profile, ask the user to run \`npx -y --package=@fnnas-labs/fnos-cli@${metadata.version} fnos-cli login --profile <profile> --host <nas-host> --port <port>\` in their real terminal. Use the user's chosen NAS host and port; ask when unknown instead of assuming localhost. An existing profile may reuse its saved endpoint by omitting the host/port options unless the user chooses another device. The terminal must be on the same DSH Host, as the same system user, with the same configuration environment (including \`TRIM_CLI_CONFIG_DIR\`) and profile as the CLI invocation. The user completes browser authorization and enters the code in that terminal. Resume the requested read-only command only after the user confirms login. Installation and Skill loading do not log in. Keep passwords and authorization codes in the user's terminal; do not request or submit them through Agent tools.
+
+The default one-shot DSH shell has no interactive login TTY. A remote browser does not share the DSH Host's session. SSH shell providers and containers may execute on a different host with different files and sessions: ask the user to install and log in in the actual execution environment before proceeding; this local package path must only be used on the host where this package is installed. macOS Keychain access may require the user's system approval.
+`
+  return ctx.skills.register({
+    name: 'fnos-cli',
+    source: 'runtime',
+    description: 'Manage fnOS NAS files, downloads, storage, apps and system state with the package-local fnOS CLI. Use for fnOS operations and authentication guidance.',
+    content: `${invocation}\n${body}`,
+    resourceBase: { kind: 'directory', path: fileURLToPath(skillDirectory) },
+  })
+}

package/npm/install.cjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+const {
+  PACKAGE_NAME,
+  PRIMARY_COMMAND,
+  copySkillAtomically,
+  resolveSkillDestination,
+  validatePackagedSkill
+} = require("./package-lib.cjs");
+
+function usage() {
+  return `Usage: ${PRIMARY_COMMAND} install [options]
+
+Install the native ${PRIMARY_COMMAND} command and its Agent Skill.
+
+Options:
+  --project      Install the Skill under ./.agents/skills instead of the user home
+  --skill-only   Install only the Skill; do not install ${PRIMARY_COMMAND} globally with npm
+  --skip-skill   Install only the global ${PRIMARY_COMMAND} command
+  -h, --help     Show this help`;
+}
+
+function parseArgs(args) {
+  const options = { project: false, skillOnly: false, skipSkill: false, help: false };
+  for (const arg of args) {
+    switch (arg) {
+      case "--project":
+        options.project = true;
+        break;
+      case "--skill-only":
+        options.skillOnly = true;
+        break;
+      case "--skip-skill":
+        options.skipSkill = true;
+        break;
+      case "-h":
+      case "--help":
+        options.help = true;
+        break;
+      default:
+        throw new Error(`Unknown install option: ${arg}`);
+    }
+  }
+  if (options.skillOnly && options.skipSkill) {
+    throw new Error("--skill-only and --skip-skill cannot be used together");
+  }
+  return options;
+}
+
+function npmCommand(platform = process.platform) {
+  return platform === "win32" ? "npm.cmd" : "npm";
+}
+
+function runNpm(command, args, options) {
+  // Windows cannot exec a .cmd shim without a shell. Invoke npm's JS entrypoint
+  // with Node instead, keeping package arguments out of shell interpolation.
+  if (process.platform === "win32" && command === "npm.cmd") {
+    const entry = path.join(path.dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js");
+    return spawnSync(process.execPath, [entry, ...args], options);
+  }
+  return spawnSync(command, args, options);
+}
+
+function globalPackageVersion(command = npmCommand()) {
+  const result = runNpm(command, ["list", "--global", PACKAGE_NAME, "--depth=0", "--json"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+  if (!result.stdout) return null;
+  try {
+    const parsed = JSON.parse(result.stdout);
+    return parsed.dependencies && parsed.dependencies[PACKAGE_NAME]
+      ? parsed.dependencies[PACKAGE_NAME].version || null
+      : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function installGlobalPackage(version, command = npmCommand()) {
+  if (globalPackageVersion(command) === version) {
+    console.log(`${PACKAGE_NAME} ${version} is already installed globally.`);
+    return;
+  }
+
+  const packageSpec = `${PACKAGE_NAME}@${version}`;
+  console.log(`Installing ${packageSpec} globally...`);
+  const result = runNpm(command, ["install", "--global", packageSpec], { stdio: "inherit" });
+  if (result.error) {
+    throw new Error(`Cannot run npm: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    throw new Error(`npm install failed with exit code ${result.status}`);
+  }
+}
+
+function main(args = process.argv.slice(2), context = {}) {
+  const options = parseArgs(args);
+  if (options.help) {
+    console.log(usage());
+    return;
+  }
+
+  const packageRoot = context.packageRoot || path.resolve(__dirname, "..");
+  const validated = validatePackagedSkill(packageRoot, {
+    platform: context.platform,
+    arch: context.arch
+  });
+
+  if (!options.skillOnly) {
+    installGlobalPackage(validated.packageJson.version, context.npmCommand);
+  }
+
+  if (!options.skipSkill) {
+    const destination = resolveSkillDestination({
+      project: options.project,
+      cwd: context.cwd,
+      homeDir: context.homeDir
+    });
+    for (const warning of copySkillAtomically(validated.skillRoot, destination)) {
+      console.warn(`Warning: ${warning}`);
+    }
+    console.log(`Agent Skill installed: ${destination}`);
+  }
+
+  console.log(`Installation complete. Existing sessions are unchanged. If needed, run \`${PRIMARY_COMMAND} login\` to start OAuth authorization.`);
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`${PRIMARY_COMMAND} install failed: ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = { globalPackageVersion, installGlobalPackage, main, npmCommand, parseArgs, runNpm, usage };