@vifu/vf 0.1.0-alpha.8

package/README.md

@@ -0,0 +1,180 @@
+# VifuHub CLI
+
+`vf` is the command-line tool for building, checking, and publishing playable
+AI-native game releases to VifuHub.
+
+```bash
+vf manifest check
+vf build
+vf deploy
+```
+
+When run from a game directory, `vf deploy` resolves the local project,
+validates `manifest.json`, builds the game, checks the Agent Runtime artifact,
+uploads only when the artifact is valid, and prints the playable URL.
+
+## Install
+
+```bash
+npm install -g @vifu/vf
+vf --help
+```
+
+The native installer is also available for macOS, Linux, and Windows shells:
+
+```bash
+curl -fsSL https://vifu.dev/cli | bash
+vf --help
+```
+
+For repeated use inside one project:
+
+```bash
+npm install --save-dev @vifu/vf
+npx vf --help
+```
+
+## Agent Workflows
+
+Install the VifuHub CLI skill separately from
+[github.com/vifudotdev/skills](https://github.com/vifudotdev/skills):
+
+```bash
+npx skills add vifudotdev/skills --skill "vifu-cli"
+```
+
+Then a coding agent can start from the current directory:
+
+```text
+Use the VifuHub CLI skill. Deploy this game directory and report the Playable URL.
+```
+
+The skill tells agents to check `vf --help`, then use the one-step deploy path:
+
+```bash
+vf deploy --yes
+```
+
+`vf deploy --yes` creates missing setup from detected defaults, builds, checks
+the output, uploads the valid artifact, and prints `Playable URL:` when sharing
+succeeds. If authentication is missing, run:
+
+```bash
+vf login
+```
+
+Create a new project:
+
+```bash
+npm create @vifu/vifu my-game -- --template vanilla --no-interactive
+cd my-game
+vf deploy --yes
+```
+
+Deploy an existing project:
+
+```bash
+cd path/to/game
+vf deploy --yes
+```
+
+You can also pass the project path explicitly:
+
+```bash
+vf deploy ./path/to/game
+```
+
+## Manifest
+
+Every deployable game has a public V1 `manifest.json`:
+
+```json
+{
+  "name": "my-ai-game"
+}
+```
+
+VifuHub fills deployable defaults and infers common build settings from the
+project. Add fields only when you need to override detection or disable an
+Agent Runtime feature. Do not put internal runtime keys such as `runtime`,
+`services`, `devices`, `resources`, `permissions`, `capabilities`, `browser`,
+or `security` in public game manifests.
+
+Useful commands:
+
+```bash
+vf manifest check
+vf manifest check --dir ./path/to/game
+vf manifest explain
+vf manifest explain --dir ./path/to/game --debug
+```
+
+`manifest explain --debug` is for Agent Runtime development. It shows the
+compiled internal policy that the runtime will enforce.
+
+## Release Policy
+
+`vf deploy` and `vf publish` treat the built output as the reviewed Agent
+Runtime artifact. The CLI does not rewrite the game, download CDN scripts, or
+create a deploy lockfile.
+
+Allowed:
+
+- bundled game JavaScript
+- local build output from Vite, Angular, Phaser, Three.js, Pixi, plain HTML, or
+  another web build tool
+- approved external static CSS, fonts, images, and media
+- AI/backend access through `@vifu/hub` or `window.Vifu`
+
+Blocked:
+
+- remote `<script src="https://...">`
+- remote JavaScript `import("https://...")`
+- remote workers or `importScripts(...)`
+- remote `.js`, `.mjs`, or `.wasm` URLs inside built files
+- direct calls to external AI/backend APIs from game JavaScript
+
+If deploy fails, read the file, line, rule, URL, and fix shown by the CLI. The
+most common cause is an optional local or third-party provider being statically
+imported into a production browser bundle.
+
+The canonical policy is [.spec/runtime-artifact-policy.md](../../.spec/runtime-artifact-policy.md).
+
+## SDK Integration
+
+Games should call Agent Runtime capabilities through the VifuHub SDK:
+
+```js
+const result = await Vifu.ai.generateText({
+  model: "quality",
+  messages: [{ role: "user", content: "Describe the next room." }]
+});
+
+await Vifu.gameState.save({ reason: "checkpoint" });
+```
+
+The SDK keeps runtime transport, host authentication, model routing, quota,
+and backend URLs out of game code. See
+[packages/sdk/README.md](../../packages/sdk/README.md).
+
+## Existing Games
+
+To adapt an existing browser game:
+
+1. Add `manifest.json`.
+2. Start with only `name`; let VifuHub infer common entry and build settings.
+3. Build a static directory with `index.html`.
+4. Replace direct AI/backend calls with the VifuHub SDK.
+5. Remove unused remote/local AI providers from the published build.
+6. Run `vf deploy`.
+
+Extra source workflows live under explicit commands:
+
+```bash
+vf remix my-remix --from ./existing-game
+vf import anki jlpt-review --apkg ./deck.apkg
+vf import podcast listening-game --feed-url https://example.com/feed.xml
+```
+
+`vf create` and `vf new` are intentionally not exposed. Use
+`npm create @vifu/vifu` for new template projects.

package/bin/vf.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+const childProcess = require("node:child_process");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const platformMap = {
+  darwin: "darwin",
+  linux: "linux",
+  win32: "windows",
+};
+
+const archMap = {
+  x64: "x64",
+  arm64: "arm64",
+};
+
+function isMusl() {
+  if (os.platform() !== "linux") return false;
+  try {
+    if (fs.existsSync("/etc/alpine-release")) return true;
+  } catch {
+    // Ignore blocked filesystem probes.
+  }
+  try {
+    const result = childProcess.spawnSync("ldd", ["--version"], {
+      encoding: "utf8",
+      windowsHide: true,
+    });
+    return `${result.stdout || ""}${result.stderr || ""}`.toLowerCase().includes("musl");
+  } catch {
+    return false;
+  }
+}
+
+function targetId() {
+  const platform = platformMap[os.platform()] || os.platform();
+  const arch = archMap[os.arch()] || os.arch();
+  if (arch !== "x64" && arch !== "arm64") {
+    throw new Error(`Unsupported VifuHub CLI architecture: ${os.arch()}`);
+  }
+  if (platform === "linux") return `linux-${arch}${isMusl() ? "-musl" : ""}`;
+  if (platform === "darwin" && (arch === "x64" || arch === "arm64")) return `darwin-${arch}`;
+  if (platform === "windows" && arch === "x64") return "windows-x64";
+  throw new Error(`Unsupported VifuHub CLI system: ${os.platform()}/${os.arch()}`);
+}
+
+function packageNames() {
+  const id = targetId();
+  const primary = `@vifu/vf-${id}`;
+  if (!id.startsWith("linux-")) return [primary];
+  if (id === "linux-x64") return [primary, "@vifu/vf-linux-x64-musl"];
+  if (id === "linux-x64-musl") return [primary, "@vifu/vf-linux-x64"];
+  if (id === "linux-arm64") return [primary, "@vifu/vf-linux-arm64-musl"];
+  if (id === "linux-arm64-musl") return [primary, "@vifu/vf-linux-arm64"];
+  return [primary];
+}
+
+function resolveBinary(packageName) {
+  const packageJsonPath = require.resolve(`${packageName}/package.json`);
+  const binaryName = os.platform() === "win32" ? "vf.exe" : "vf";
+  const binaryPath = path.join(path.dirname(packageJsonPath), "bin", binaryName);
+  if (!fs.existsSync(binaryPath)) {
+    throw new Error(`Binary not found at ${binaryPath}`);
+  }
+  return binaryPath;
+}
+
+function main() {
+  const errors = [];
+  for (const packageName of packageNames()) {
+    try {
+      const binaryPath = resolveBinary(packageName);
+      const result = childProcess.spawnSync(binaryPath, process.argv.slice(2), {
+        stdio: "inherit",
+        windowsHide: false,
+      });
+      if (result.error) throw result.error;
+      if (result.signal) {
+        process.kill(process.pid, result.signal);
+        return;
+      }
+      process.exit(typeof result.status === "number" ? result.status : 1);
+    } catch (error) {
+      errors.push(`${packageName}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  console.error("Unable to find the VifuHub CLI binary for this system.");
+  console.error("Tried:");
+  for (const error of errors) console.error(`  - ${error}`);
+  console.error("Reinstall @vifu/vf and make sure optional dependencies are enabled.");
+  process.exit(1);
+}
+
+main();

package/install.sh

@@ -0,0 +1,333 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+PROGRAM_NAME="vf"
+NPM_PACKAGE_NAME="${VIFU_NPM_PACKAGE:-@vifu/vf}"
+MANIFEST_URL="${VIFU_VERSION_MANIFEST_URL:-https://vifu.dev/cli/version.json}"
+STATE_DIR="${VIFU_STATE_DIR:-$HOME/.vifu}"
+VERSION_INSTALL_PATH="${STATE_DIR}/version.json"
+
+tmp_dir=""
+npm_package_name="$NPM_PACKAGE_NAME"
+
+say() {
+  printf '%s\n' "$*"
+}
+
+fail() {
+  printf 'VifuHub CLI install: %s\n' "$*" >&2
+  exit 1
+}
+
+cleanup() {
+  if [ -n "$tmp_dir" ]; then
+    rm -rf "$tmp_dir"
+  fi
+}
+
+has_command() {
+  command -v "$1" >/dev/null 2>&1
+}
+
+download_file() {
+  local url="$1"
+  local output="$2"
+
+  if has_command curl; then
+    curl -fsSL "$url" -o "$output"
+    return
+  fi
+  if has_command wget; then
+    wget -qO "$output" "$url"
+    return
+  fi
+
+  fail "curl or wget is required"
+}
+
+append_line_if_missing() {
+  local file="$1"
+  local line="$2"
+
+  mkdir -p "$(dirname "$file")"
+  touch "$file"
+  if ! grep -Fqx "$line" "$file"; then
+    printf '\n%s\n' "$line" >>"$file"
+  fi
+}
+
+pick_unix_rc_file() {
+  local shell_name
+  shell_name="$(basename "${SHELL:-}")"
+
+  case "$shell_name" in
+    zsh)
+      printf '%s\n' "${ZDOTDIR:-$HOME}/.zshrc"
+      ;;
+    bash)
+      if [ -f "$HOME/.bashrc" ] || [ ! -f "$HOME/.bash_profile" ]; then
+        printf '%s\n' "$HOME/.bashrc"
+      else
+        printf '%s\n' "$HOME/.bash_profile"
+      fi
+      ;;
+    *)
+      printf '%s\n' "$HOME/.profile"
+      ;;
+  esac
+}
+
+ensure_unix_path() {
+  local install_dir="$1"
+  local rc_file
+
+  case ":$PATH:" in
+    *":$install_dir:"*)
+      say "PATH already contains $install_dir"
+      return
+      ;;
+  esac
+
+  rc_file="$(pick_unix_rc_file)"
+  append_line_if_missing "$rc_file" "export PATH=\"$install_dir:\$PATH\""
+  say "Added $install_dir to PATH startup file: $rc_file"
+  say "For this terminal, run: export PATH=\"$install_dir:\$PATH\""
+}
+
+windows_path_contains() {
+  local install_dir="$1"
+  case ";${PATH};" in
+    *";${install_dir};"*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+ensure_windows_path() {
+  local install_dir="$1"
+  local install_dir_windows
+
+  if windows_path_contains "$install_dir"; then
+    say "PATH already contains $install_dir"
+    return
+  fi
+
+  if ! has_command powershell.exe; then
+    say "powershell.exe not found; add $install_dir to your user PATH manually"
+    return
+  fi
+
+  if has_command cygpath; then
+    install_dir_windows="$(cygpath -w "$install_dir")"
+  else
+    install_dir_windows="$install_dir"
+  fi
+
+  powershell.exe -NoProfile -Command \
+    "\$target='${install_dir_windows}'; \$current=[Environment]::GetEnvironmentVariable('Path','User'); if ([string]::IsNullOrWhiteSpace(\$current)) { [Environment]::SetEnvironmentVariable('Path', \$target, 'User') } elseif (-not (\$current.Split(';') -contains \$target)) { [Environment]::SetEnvironmentVariable('Path', \$current + ';' + \$target, 'User') }"
+
+  say "Added $install_dir to Windows user PATH"
+}
+
+clear_macos_quarantine() {
+  local target="$1"
+
+  if ! has_command xattr; then
+    return
+  fi
+
+  xattr -d com.apple.quarantine "$target" >/dev/null 2>&1 || true
+}
+
+detect_linux_libc_suffix() {
+  if has_command ldd && ldd --version 2>&1 | grep -qi musl; then
+    printf '%s\n' "-musl"
+    return
+  fi
+  if ls /lib/ld-musl-* >/dev/null 2>&1 || ls /usr/lib/ld-musl-* >/dev/null 2>&1; then
+    printf '%s\n' "-musl"
+    return
+  fi
+  printf '%s\n' ""
+}
+
+detect_platform() {
+  local os
+  local arch
+  local os_id
+  local arch_id
+  local libc_suffix
+
+  os="$(uname -s 2>/dev/null || true)"
+  arch="$(uname -m 2>/dev/null || true)"
+
+  case "$os" in
+    Darwin)
+      os_id="darwin"
+      PLATFORM_KIND="unix"
+      DEFAULT_INSTALL_DIR="${VIFU_INSTALL_DIR:-${VIFU_CLI_INSTALL_DIR:-$HOME/.local/bin}}"
+      ;;
+    Linux)
+      os_id="linux"
+      PLATFORM_KIND="unix"
+      DEFAULT_INSTALL_DIR="${VIFU_INSTALL_DIR:-${VIFU_CLI_INSTALL_DIR:-$HOME/.local/bin}}"
+      ;;
+    MINGW*|MSYS*|CYGWIN*)
+      os_id="windows"
+      PLATFORM_KIND="windows"
+      DEFAULT_INSTALL_DIR="${VIFU_INSTALL_DIR:-${VIFU_CLI_INSTALL_DIR:-$HOME/bin}}"
+      ;;
+    *)
+      fail "unsupported operating system: ${os:-unknown}"
+      ;;
+  esac
+
+  case "$arch" in
+    arm64|aarch64)
+      arch_id="arm64"
+      ;;
+    x86_64|amd64)
+      arch_id="x64"
+      ;;
+    *)
+      fail "unsupported CPU architecture: ${arch:-unknown}"
+      ;;
+  esac
+
+  libc_suffix=""
+  if [ "$os_id" = "linux" ]; then
+    libc_suffix="$(detect_linux_libc_suffix)"
+  fi
+
+  TARGET_ID="${VIFU_INSTALL_TARGET:-${os_id}-${arch_id}${libc_suffix}}"
+}
+
+json_value() {
+  local key="$1"
+  local file="$2"
+  sed -n "s/.*\"$key\"[[:space:]]*:[[:space:]]*\"\\([^\"]*\\)\".*/\\1/p" "$file" | head -n 1
+}
+
+target_json_value() {
+  local target="$1"
+  local key="$2"
+  local file="$3"
+
+  sed -n "/\"$target\"[[:space:]]*:/,/^[[:space:]]*}/p" "$file" \
+    | sed -n "s/.*\"$key\"[[:space:]]*:[[:space:]]*\"\\([^\"]*\\)\".*/\\1/p" \
+    | head -n 1
+}
+
+try_npm_fallback() {
+  if [ "${VIFU_NO_NPM_FALLBACK:-}" = "1" ]; then
+    return 1
+  fi
+  if ! has_command npm; then
+    return 1
+  fi
+
+  say "Native package unavailable; falling back to npm install -g ${npm_package_name}"
+  npm install -g "${npm_package_name}"
+  return 0
+}
+
+main() {
+  local manifest_file
+  local archive_file
+  local package_dir
+  local package_root
+  local package_url
+  local binary_rel
+  local binary_path
+  local install_path
+  local version
+  local manifest_package
+  local target_name
+
+  detect_platform
+
+  if ! has_command tar; then
+    fail "tar is required"
+  fi
+
+  tmp_dir="$(mktemp -d 2>/dev/null || mktemp -d -t vifuhub-cli)"
+  trap cleanup EXIT INT TERM
+
+  manifest_file="$tmp_dir/version.json"
+  archive_file="$tmp_dir/vifuhub-cli.tgz"
+  package_dir="$tmp_dir/package"
+
+  say "Downloading $MANIFEST_URL"
+  download_file "$MANIFEST_URL" "$manifest_file"
+
+  version="$(json_value version "$manifest_file")"
+  manifest_package="$(json_value package "$manifest_file")"
+  if [ -n "$manifest_package" ]; then
+    npm_package_name="$manifest_package"
+  fi
+
+  package_url="$(target_json_value "$TARGET_ID" url "$manifest_file")"
+  binary_rel="$(target_json_value "$TARGET_ID" binary "$manifest_file")"
+
+  if [ -z "$package_url" ] || [ -z "$binary_rel" ]; then
+    say "No native VifuHub CLI package is listed for target: $TARGET_ID" >&2
+    try_npm_fallback && exit 0
+    fail "use npm install -g ${npm_package_name}"
+  fi
+
+  say "Installing VifuHub CLI ${version:-latest} for $TARGET_ID"
+  say "Downloading $package_url"
+  if ! download_file "$package_url" "$archive_file"; then
+    say "Failed to download native package: $package_url" >&2
+    try_npm_fallback && exit 0
+    fail "download failed"
+  fi
+
+  mkdir -p "$package_dir"
+  tar -xzf "$archive_file" -C "$package_dir"
+  package_root="$package_dir/package"
+  binary_path="$package_root/$binary_rel"
+  if [ ! -f "$binary_path" ]; then
+    fail "package did not contain $binary_rel"
+  fi
+
+  case "$binary_rel" in
+    *.exe) target_name="${PROGRAM_NAME}.exe" ;;
+    *) target_name="$PROGRAM_NAME" ;;
+  esac
+
+  mkdir -p "$DEFAULT_INSTALL_DIR"
+  install_path="$DEFAULT_INSTALL_DIR/$target_name"
+  cp "$binary_path" "$install_path"
+  chmod 755 "$install_path"
+
+  mkdir -p "$STATE_DIR"
+  cp "$manifest_file" "$VERSION_INSTALL_PATH"
+  say "Version manifest: $VERSION_INSTALL_PATH"
+
+  case "$PLATFORM_KIND" in
+    unix)
+      ensure_unix_path "$DEFAULT_INSTALL_DIR"
+      ;;
+    windows)
+      ensure_windows_path "$DEFAULT_INSTALL_DIR"
+      ;;
+  esac
+
+  if [ "$(uname -s 2>/dev/null || true)" = "Darwin" ]; then
+    clear_macos_quarantine "$install_path"
+  fi
+
+  say "VifuHub CLI installed: $install_path"
+  if "$install_path" --help >/dev/null 2>&1; then
+    say "Command check: ok"
+  else
+    say "Command check: $install_path --help failed; inspect the binary before using it" >&2
+  fi
+
+  say "Try:"
+  say "  vf --help"
+  say "  vf deploy --yes"
+}
+
+main "$@"

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@vifu/vf",
+  "version": "0.1.0-alpha.8",
+  "description": "VifuHub CLI for building, checking, and publishing AI-native games.",
+  "bin": {
+    "vf": "bin/vf.js"
+  },
+  "files": [
+    "bin/vf.js",
+    "README.md",
+    "install.sh",
+    "version.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "optionalDependencies": {
+    "@vifu/vf-darwin-arm64": "0.1.0-alpha.8",
+    "@vifu/vf-darwin-x64": "0.1.0-alpha.8",
+    "@vifu/vf-linux-arm64": "0.1.0-alpha.8",
+    "@vifu/vf-linux-arm64-musl": "0.1.0-alpha.8",
+    "@vifu/vf-linux-x64": "0.1.0-alpha.8",
+    "@vifu/vf-linux-x64-musl": "0.1.0-alpha.8",
+    "@vifu/vf-windows-x64": "0.1.0-alpha.8"
+  }
+}

package/version.json

@@ -0,0 +1,35 @@
+{
+  "version": "0.1.0-alpha.8",
+  "package": "@vifu/vf",
+  "installer": "https://vifu.dev/cli",
+  "targets": {
+    "darwin-arm64": {
+      "url": "https://registry.npmjs.org/@vifu/vf-darwin-arm64/-/vf-darwin-arm64-0.1.0-alpha.8.tgz",
+      "binary": "bin/vf"
+    },
+    "darwin-x64": {
+      "url": "https://registry.npmjs.org/@vifu/vf-darwin-x64/-/vf-darwin-x64-0.1.0-alpha.8.tgz",
+      "binary": "bin/vf"
+    },
+    "linux-arm64": {
+      "url": "https://registry.npmjs.org/@vifu/vf-linux-arm64/-/vf-linux-arm64-0.1.0-alpha.8.tgz",
+      "binary": "bin/vf"
+    },
+    "linux-arm64-musl": {
+      "url": "https://registry.npmjs.org/@vifu/vf-linux-arm64-musl/-/vf-linux-arm64-musl-0.1.0-alpha.8.tgz",
+      "binary": "bin/vf"
+    },
+    "linux-x64": {
+      "url": "https://registry.npmjs.org/@vifu/vf-linux-x64/-/vf-linux-x64-0.1.0-alpha.8.tgz",
+      "binary": "bin/vf"
+    },
+    "linux-x64-musl": {
+      "url": "https://registry.npmjs.org/@vifu/vf-linux-x64-musl/-/vf-linux-x64-musl-0.1.0-alpha.8.tgz",
+      "binary": "bin/vf"
+    },
+    "windows-x64": {
+      "url": "https://registry.npmjs.org/@vifu/vf-windows-x64/-/vf-windows-x64-0.1.0-alpha.8.tgz",
+      "binary": "bin/vf.exe"
+    }
+  }
+}