Nutget CLI

Composer-like package manager dla projektów Squirrel i skryptów .nut.

To nie jest już bashowy wrapper. Repo zostało przepisane na przenośne CLI Node.js, które:

• działa na macOS, Linux i Windows
• instaluje się jak normalne narzędzie CLI przez npm
• trzyma zależności w vendor/
• generuje nutget.lock
• buduje var/cache/autoload.nut
• obsługuje źródła git, path, auto-discovery lokalnych workspace'ów i prywatne registry
• ma globalną konfigurację ~/.nutget/config.json
• potrafi publikować pakiety do registry

Instalacja

Masz teraz 3 realne ścieżki instalacji.

Lokalnie z repo:

npm install
node ./bin/nutget.js help

Globalnie:

npm install -g .
nutget help

Z npm po publikacji:

npm install -g nutget
nutget help

Na Windows npm wygeneruje shim polecenia automatycznie, więc nutget działa też z cmd i PowerShell.

Bez instalacji globalnej:

npx nutget help

Bez Node na maszynie użytkownika:

1. wejdź w GitHub Releases
2. pobierz binarkę nutget-linux-x64, nutget-darwin-arm64, nutget-win32-x64.exe albo odpowiednią dla platformy
3. wrzuć ją do PATH

To jest generowane automatycznie przez workflow release.

Albo one-liner:

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/SzymonKostrubiec/Acorn-FileManager/main/scripts/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/SzymonKostrubiec/Acorn-FileManager/main/scripts/install.ps1 | iex

Publikacja do npm

Repo ma już przygotowane:

• files w package.json, więc do npm nie poleci cały syf z repo
• prepublishOnly, więc przed publish leci smoke i npm pack --dry-run
• workflow publish.yml, który publikuje paczkę przez GitHub Actions
• workflow release-binaries.yml, który buduje gotowe binarki

Manualnie:

npm login
npm publish --access public

Docelowo lepiej używać trusted publishing z GitHub Actions niż stałego tokena npm.

Pełny checklist masz w docs/release-and-install.md.

Paczka npm publikuje zbundlowany runtime dist/nutget.cjs, więc użytkownik z npm dostaje gotowe CLI, a nie całe drzewo źródeł.

Build binarek

Lokalnie po npm install:

npm run build:bundle
npm run build:binary

To zbuduje:

• dist/nutget.cjs
• dist/nutget-<platform>-<arch>
• dist/nutget-<platform>-<arch>.sha256

Globalna konfiguracja

To jest kluczowy element, którego brakowało w pierwszej wersji. Projekt może mieć tylko require, a źródła pakietów konfigurujesz globalnie:

nutget config init
nutget config show

Plik globalny:

{
  "repositories": [
    {
      "type": "registry",
      "url": "https://packages.example.com",
      "tokenEnv": "NUTGET_REGISTRY_TOKEN"
    }
  ],
  "workspaces": [
    {
      "path": "~/Projects",
      "depth": 3
    }
  ],
  "publish": {
    "registry": "https://packages.example.com",
    "tokenEnv": "NUTGET_REGISTRY_TOKEN",
    "endpoint": "/publish"
  }
}

workspaces służy do automatycznego wykrywania lokalnych pakietów nutget.json lub acorn.json, więc w projekcie możesz mieć samo require, a CLI samo znajdzie lokalne repo, jeśli jest obecne w twoim workspace.

Jeśli lokalny pakiet i zdalne registry mają tę samą nazwę, jawne repositories projektu wygrywają, a gdy ich brak, local workspace może podmienić zdalne źródło w development workflow.

Format projektu

Plik projektu to nutget.json. Dla kompatybilności CLI czyta też stare acorn.json.

Przykład:

{
  "name": "my-acorn-app",
  "type": "project",
  "config": {
    "vendor_dir": "vendor",
    "cache_dir": "var/cache",
    "storage_dir": "var/storage",
    "logs_dir": "var/logs",
    "lock_file": "nutget.lock",
    "autoload_output_file": "var/cache/autoload.nut"
  },
  "autoload": {
    "files": [
      "src/**/*.nut"
    ]
  },
  "require": {
    "acorn/framework": "dev-main"
  }
}

repositories w projekcie są nadal wspierane, ale są opcjonalne. Jeśli masz dobrze ustawione globalne registry i workspaces, projekt może zawierać praktycznie tylko require.

Format pakietu

Każdy pakiet ma własny nutget.json albo starszy acorn.json.

{
  "name": "acorn/framework",
  "version": "2.1.0",
  "autoload": {
    "files": [
      "app/**/*.nut"
    ]
  },
  "require": {
    "acorn/support": "^1.4.0"
  }
}

Komendy

nutget install
nutget update
nutget dump-autoload
nutget clear
nutget doctor
nutget publish
nutget config init
nutget config show
nutget help

Jak to działa

install:

1. czyta nutget.json albo acorn.json
2. jeśli jest nutget.lock, instaluje z locka
3. pobiera zależności do vendor/
4. skanuje autoload.files z projektu i pakietów
5. generuje var/cache/autoload.nut
6. zapisuje nowy nutget.lock

update:

1. odświeża repozytoria do najnowszych dozwolonych referencji
2. regeneruje autoload
3. przepisuje nutget.lock

dump-autoload:

1. nie pobiera nowych paczek
2. skanuje już zainstalowany kod
3. odświeża autoload.nut
4. synchronizuje nutget.lock

publish:

1. czyta bieżący nutget.json albo acorn.json
2. bierze origin z Gita oraz aktualny HEAD
3. wysyła metadane pakietu do registry
4. od tego momentu inny projekt może mieć samo require

Typy repozytoriów

git

Najprostszy tryb dla prywatnego frameworka:

{
  "type": "git",
  "package": "acorn/framework",
  "url": "ssh://[email protected]/acorn/framework.git",
  "branch": "main"
}

path

Do lokalnego developmentu pakietu:

{
  "type": "path",
  "package": "acorn/framework",
  "source": "../Acorn"
}

registry

Jeśli chcesz prywatny serwer metadanych podobny do Packagista:

{
  "type": "registry",
  "url": "https://packages.example.com",
  "tokenEnv": "NUTGET_REGISTRY_TOKEN"
}

Kontrakt API i konfiguracja reverse proxy są opisane w docs/server.md.

Workflow bez ręcznych repositories

1. Pakiet frameworka ma własne repo Git i nutget.json.
2. Publikujesz go przez nutget publish.
3. Registry zapisuje metadane name/version/source/autoload/require.
4. Projekt aplikacji wpisuje tylko:

{
  "require": {
    "acorn/framework": "^2.1.0"
  }
}

5. nutget install respektuje jawne repositories z projektu, a jeśli ich brak dla danej paczki, sprawdza lokalne workspace i globalne registry.

Migracja ze starego formatu

CLI nadal potrafi czytać stary układ:

{
  "packages": [
    {
      "name": "acorn",
      "version": "dev-main",
      "autoload": {
        "repos": [
          {
            "url": "https://github.com/org/Acorn.git",
            "branch": "main",
            "path": "vendor/acorn"
          }
        ]
      }
    }
  ]
}

Ale docelowo trzymaj się układu require + repositories, bo to jest baza pod dalszy rozwój solvera zależności.