@remarkkpt/foundry-installer 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# Instalador Foundry para macOS
 
-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.
+Este pacote público contém apenas o percurso de obtenção. A Foundry permanece
+privada em `RemarkkPT/Foundry-V2`. É necessário um convite; um convidado pode ver
+o código desse repositório. Cada pessoa utiliza o seu próprio login GitHub.
+
+Num terminal do macOS, executa (precisa do Node/npm):
+
+```sh
+npx @remarkkpt/foundry-installer
+```
+
+Alternativa preparada para Macs sem Node/npm, só após publicar 0.1.1:
+
+```sh
+installer="$(curl -fsSL https://unpkg.com/@remarkkpt/foundry-installer@0.1.1/install.sh)" && /bin/bash -c "$installer"
+```
+
+A alternativa `curl` não exige Node/npm para arrancar. Mantém-se `@0.1.1`
+para executar o script desta versão, sem mudar para futuras versões automaticamente.
+
+O instalador oferece preparar os
+requisitos com confirmação, confere o acesso e obtém os assets `foundry.tgz` e
+`foundry-release.json` da release privada `v0.1.0-alpha.1`. Confere o
+SHA-256, instala uma vez por Mac e abre a seleção visual de projeto no terminal.
+Não clona nem compila a Foundry, nem altera a visibilidade de repositórios. O script não extrai palavras-passe nem tokens; usa o teu login no GitHub CLI para confirmar o acesso e descarregar a versão privada.
+
+A instalação usa `~/.local/share/foundry` e `~/.local/bin/foundry`. A preparação
+do PATH, quando necessária, acrescenta uma linha ao perfil da shell apenas com
+confirmação; o conteúdo existente é preservado. Uma instalação adequada é
+reutilizada. Falhas de descarga/instalação preservam a versão ativa anterior.
+O prefixo npm anteriormente documentado em `~/.local/share/foundry/node_modules`
+também é reutilizado: os seus ficheiros são conferidos contra o pacote da release
+com SHA-256 validado e o comando existente é conservado. O launcher documentado anterior é reconhecido pelo conteúdo integral. Se a versão
+for diferente, o instalador explica e pede confirmação para atualizar. Só depois
+de verificar a nova CLI move o prefixo anterior para
+`~/.local/share/foundry/backups/legacy-…`, juntamente com o launcher, e indica
+o backup. Recusar preserva tudo. Se a ativação falhar antes de o novo comando ficar ativo, o instalador tenta repor o prefixo e o comando anteriores. Se o prefixo for reposto, regressa à localização original; caso contrário, permanece no backup indicado. Depois de o novo comando ficar ativo, não há restauro automático e o backup é conservado.
+Com o launcher documentado, também se oferece atualização confirmada quando
+os ficheiros diferem apesar de terem o mesmo número de versão. Sem esse launcher,
+a mesma versão divergente é preservada e recusada para conferência manual.
+
+Este pacote não contém credenciais nem publica código. O acesso à Foundry
+continua limitado aos convidados do repositório privado.

package/install.sh

@@ -0,0 +1,244 @@
+#!/bin/bash
+set -euo pipefail
+fail() { printf '\n%s\n' "$*" >&2; exit 1; }
+confirm() { local answer; printf '%s [s/N] ' "$1"; read -r answer || return 1; [[ "$answer" == s || "$answer" == S ]]; }
+[[ "$(uname -s)" == Darwin ]] || fail 'Este instalador suporta macOS.'
+[[ -t 0 && -t 1 ]] || fail 'Abra um terminal interativo para executar o instalador.'
+# Keep existing working tools; never link/upgrade a personal installation silently.
+export PATH="${PATH}:/opt/homebrew/bin:/usr/local/bin"
+prepare_tool() {
+  local formula="$1"
+  printf 'É necessário preparar %s para obter e abrir a Foundry.\n' "$formula"
+  confirm "Preparar $formula com Homebrew?" || fail 'Instalação cancelada; requisito em falta.'
+  if ! command -v brew >/dev/null 2>&1; then
+    printf 'Homebrew instala ferramentas de desenvolvimento e pode pedir autorização do macOS.\n'
+    confirm 'Instalar Homebrew a partir do instalador oficial?' || fail 'Instalação cancelada; Homebrew em falta.'
+    local script
+    script=$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh) || fail 'Não foi possível obter o instalador Homebrew.'
+    /bin/bash -c "$script" || fail 'A preparação do Homebrew falhou.'
+  fi
+  command -v brew >/dev/null 2>&1 || fail 'Homebrew não ficou disponível.'
+  brew install "$formula" || fail "Não foi possível preparar $formula. A configuração existente foi preservada."
+}
+if ! command -v gh >/dev/null 2>&1; then prepare_tool gh; fi
+command -v gh >/dev/null 2>&1 || fail 'GitHub CLI continua indisponível.'
+if ! gh auth status --hostname github.com >/dev/null 2>&1; then
+  printf 'A Foundry está num repositório privado. O login é feito pelo próprio GitHub CLI.\n'
+  confirm 'Iniciar sessão no GitHub?' || fail 'Instalação cancelada; autenticação necessária.'
+  gh auth login --hostname github.com --web --git-protocol https || fail 'O login GitHub não terminou com sucesso.'
+  gh auth status --hostname github.com >/dev/null 2>&1 || fail 'A autenticação GitHub continua indisponível.'
+fi
+repository=RemarkkPT/Foundry-V2
+if ! identity=$(gh repo view "$repository" --json nameWithOwner --jq .nameWithOwner 2>/dev/null) || [[ "$identity" != "$repository" ]]; then
+  fail 'Não foi possível confirmar acesso a RemarkkPT/Foundry-V2. Precisa de um convite para este repositório privado. Um convidado passa a poder ver o código. Confirme também a ligação ao GitHub e volte a tentar.'
+fi
+# Access is checked before any private release download or installation.
+node_ok() { command -v node >/dev/null 2>&1 && node -e 'process.exit(process.versions.node.split(".")[0] === "24" ? 0 : 1)' >/dev/null 2>&1 && command -v npm >/dev/null 2>&1 && npm --version >/dev/null 2>&1; }
+if ! node_ok; then
+  for node_bin in /opt/homebrew/opt/node@24/bin /usr/local/opt/node@24/bin; do
+    if [[ -x "$node_bin/node" && -x "$node_bin/npm" ]]; then export PATH="$node_bin:$PATH"; break; fi
+  done
+fi
+if ! node_ok; then
+  prepare_tool node@24
+  node_bin="$(brew --prefix node@24)/bin"
+  export PATH="$node_bin:$PATH"
+fi
+node_ok || fail 'Node 24 e npm não ficaram disponíveis; a Foundry ainda não pode abrir.'
+if ! command -v git >/dev/null 2>&1 || ! git --version >/dev/null 2>&1; then prepare_tool git; fi
+git --version >/dev/null 2>&1 || fail 'Git continua indisponível.'
+node_executable=$(node -p 'process.execPath')
+version=0.1.0-alpha.1
+tag="v$version"
+base="$HOME/.local/share/foundry"
+bin="$HOME/.local/bin"
+for item in "$HOME/.local" "$HOME/.local/share" "$base" "$base/versions" "$base/backups" "$bin"; do
+  [[ ! -L "$item" ]] || fail "Destino simbólico inesperado: $item. Nenhuma instalação substituída."
+done
+mkdir -p "$base/versions" "$bin"
+launcher="$bin/foundry"
+legacy_launcher=false
+if [[ -f "$launcher" && ! -L "$launcher" ]]; then
+  # Recognize the complete documented 17/10 launcher, scoped to this HOME.
+  # A comment or a substring alone must never authorize replacing a command.
+  if node - "$launcher" "$HOME" <<'JS'
+const fs = require('node:fs');
+const expected = '#!/bin/sh\n# Foundry uses Node 24 without changing the default Node for other tools.\nPATH="/opt/homebrew/opt/node@24/bin:$PATH"\nexport PATH\nexec /opt/homebrew/opt/node@24/bin/node ' + process.argv[3] + '/.local/share/foundry/node_modules/@remarkkpt/foundry/dist/cli.js "$@"\n';
+process.exit(fs.readFileSync(process.argv[2], 'utf8') === expected ? 0 : 1);
+JS
+  then legacy_launcher=true; fi
+fi
+if [[ -e "$launcher" || -L "$launcher" ]]; then
+  if [[ "$legacy_launcher" != true ]]; then
+    [[ -f "$launcher" && ! -L "$launcher" ]] && grep -qx '# Foundry bootstrap launcher v1' "$launcher" || fail 'Já existe outro comando em ~/.local/bin/foundry; foi preservado. Confira esse comando e guarde-o noutro local antes de repetir o instalador.'
+  fi
+fi
+work=$(mktemp -d "$base/versions/.prepare-XXXXXXXX")
+printf 'A conferir a versão privada %s…\n' "$tag"
+gh release download "$tag" --repo "$repository" --pattern foundry-release.json --dir "$work" || fail 'Não foi possível obter a versão preparada. A primeira release pode ainda aguardar publicação autorizada.'
+metadata=$(node - "$work/foundry-release.json" "$tag" "$version" <<'JS'
+const fs = require('node:fs');
+const m = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+if (m.schema_version !== 1 || m.repository !== 'RemarkkPT/Foundry-V2' || m.tag !== process.argv[3] || m.version !== process.argv[4] || m.asset !== 'foundry.tgz' || !/^[a-f0-9]{40}$/.test(m.commit) || !/^[a-f0-9]{64}$/.test(m.sha256)) throw Error('Identidade da release inválida');
+console.log(m.commit + ' ' + m.sha256);
+JS
+) || fail 'O manifesto da versão não tem identidade válida; instalação recusada.'
+read -r commit digest <<< "$metadata"
+download_package() {
+  if [[ ! -f "$work/foundry.tgz" ]]; then
+    gh release download "$tag" --repo "$repository" --pattern foundry.tgz --dir "$work" || fail 'A descarga falhou; a instalação anterior foi preservada.'
+  fi
+  local actual
+  actual=$(/usr/bin/shasum -a 256 "$work/foundry.tgz"); actual=${actual%% *}
+  [[ "$actual" == "$digest" ]] || fail 'SHA-256 divergente; instalação recusada. A versão anterior foi preservada.'
+}
+# The previous documented npm prefix has no bootstrap receipt. Verify its
+# installed files against the identified artifact rather than trusting version.
+legacy="$base/node_modules/@remarkkpt/foundry"
+reuse_legacy=false
+update_legacy=false
+legacy_backup=
+legacy_moved=false
+restore_legacy() {
+  local status=$?
+  if [[ "$status" != 0 && "$legacy_moved" == true ]]; then
+    if mv "$legacy_backup/node_modules" "$base/node_modules"; then
+      if [[ -f "$legacy_backup/foundry" ]]; then cp -p "$legacy_backup/foundry" "$launcher"; fi
+      printf 'A instalação anterior foi reposta; backup: %s\n' "$legacy_backup" >&2
+    else printf 'A instalação anterior está no backup: %s. Reponha node_modules antes de repetir.\n' "$legacy_backup" >&2; fi
+  fi
+}
+trap restore_legacy EXIT
+if [[ -e "$legacy" || -L "$legacy" ]]; then
+  download_package
+  /usr/bin/tar -xzf "$work/foundry.tgz" -C "$work" || fail 'Não foi possível conferir o pacote; a instalação anterior foi preservada.'
+  legacy_version=$(node - "$legacy" <<'JS'
+const fs = require('node:fs'), path = require('node:path');
+for (let dir = process.argv[2]; dir !== path.dirname(dir); dir = path.dirname(dir)) {
+  if (fs.lstatSync(dir).isSymbolicLink()) throw Error('Symbolic package directory');
+}
+const pkg = JSON.parse(fs.readFileSync(path.join(process.argv[2], 'package.json')));
+if (pkg.name !== '@remarkkpt/foundry' || !/^[0-9]+\.[0-9]+\.[0-9]+(?:-[a-zA-Z0-9.-]+)?$/.test(pkg.version)) throw Error('Invalid previous package');
+console.log(pkg.version);
+JS
+  ) || fail 'Não foi possível identificar a instalação anterior; foi preservada. Confira o pacote antes de repetir.'
+  if [[ "$legacy_version" != "$version" ]]; then
+    printf 'A Foundry anterior é a versão %s; a versão preparada é %s. A atualização guarda a anterior num backup identificado.\n' "$legacy_version" "$version"
+    confirm "Atualizar Foundry para $version, guardando a instalação anterior?" || fail 'Atualização cancelada; instalação e comando anteriores preservados.'
+    update_legacy=true
+  else
+  if ! node - "$work/package" "$legacy" "$version" "$base/node_modules/.bin/foundry" <<'JS'
+const fs = require('node:fs'), path = require('node:path');
+const [expected, installed, version, executable] = process.argv.slice(2);
+// Never follow a symlink through a package directory when verifying identity.
+for (let dir = installed; dir !== path.dirname(dir); dir = path.dirname(dir)) {
+  if (fs.lstatSync(dir).isSymbolicLink()) throw Error('Symbolic package directory');
+}
+const pkg = JSON.parse(fs.readFileSync(path.join(installed, 'package.json')));
+if (pkg.name !== '@remarkkpt/foundry' || pkg.version !== version) throw Error('Package identity differs');
+function compare(relative = '') {
+  const source = path.join(expected, relative), target = path.join(installed, relative);
+  const a = fs.lstatSync(source), b = fs.lstatSync(target);
+  if (a.isDirectory() && b.isDirectory()) {
+    for (const entry of fs.readdirSync(source)) compare(path.join(relative, entry));
+  } else if (!a.isFile() || !b.isFile() || !fs.readFileSync(source).equals(fs.readFileSync(target))) {
+    throw Error('Installed file differs: ' + relative);
+  }
+}
+compare();
+if (fs.realpathSync(executable) !== path.join(installed, 'dist/cli.js')) throw Error('Command points elsewhere');
+fs.accessSync(executable, fs.constants.X_OK);
+JS
+  then
+    if [[ "$legacy_launcher" == true ]]; then
+      printf 'A instalação anterior tem a mesma versão, mas difere da versão preparada. A atualização guarda os ficheiros anteriores num backup identificado.\n'
+      confirm "Atualizar Foundry para $version, guardando a instalação anterior?" || fail 'Atualização cancelada; instalação e comando anteriores preservados.'
+      update_legacy=true
+    else fail 'A instalação anterior não corresponde à versão preparada; foi preservada. Confira-a antes de voltar a instalar.'; fi
+  else
+    "$node_executable" "$legacy/dist/cli.js" --help >/dev/null 2>&1 || fail 'A instalação anterior não arranca; foi preservada. Confira-a antes de voltar a instalar.'
+    reuse_legacy=true
+    printf 'A instalação adequada desta versão foi preservada no prefixo npm anterior.\n'
+  fi
+  fi
+fi
+if [[ "$legacy_launcher" == true && ! -d "$legacy" ]]; then fail 'O launcher anterior foi reconhecido, mas falta o pacote. Reponha a instalação anterior ou guarde o launcher antes de repetir.'; fi
+target="$base/versions/$digest"
+adequate=false
+if [[ "$reuse_legacy" == true ]]; then
+  if [[ "$legacy_launcher" != true ]]; then
+    bin="$base/node_modules/.bin"
+    launcher="$bin/foundry"
+  fi
+else
+if [[ -d "$target" && ! -L "$target" && -f "$target/receipt.json" ]]; then
+  if node - "$target/receipt.json" "$commit" "$digest" <<'JS'
+const fs = require('node:fs'); const m = JSON.parse(fs.readFileSync(process.argv[2]));
+process.exit(m.commit === process.argv[3] && m.sha256 === process.argv[4] ? 0 : 1);
+JS
+  then
+    if "$node_executable" "$target/node_modules/@remarkkpt/foundry/dist/cli.js" --help >/dev/null 2>&1; then adequate=true; fi
+  fi
+fi
+if [[ "$adequate" == false ]]; then
+  [[ ! -e "$target" && ! -L "$target" ]] || fail 'A cópia desta versão não passou a verificação; foi preservada para inspeção.'
+  if [[ "$update_legacy" != true ]]; then
+    confirm "Instalar Foundry $version (commit $commit) uma vez neste Mac?" || fail 'Instalação cancelada.'
+  fi
+  download_package
+  npm install --prefix "$work" --offline --ignore-scripts --no-save --no-audit --no-fund "$work/foundry.tgz" || fail 'A instalação falhou; a versão anterior foi preservada.'
+  node - "$work/node_modules/@remarkkpt/foundry/package.json" "$version" <<'JS'
+const fs = require('node:fs'); const p = JSON.parse(fs.readFileSync(process.argv[2]));
+if (p.name !== '@remarkkpt/foundry' || p.version !== process.argv[3]) throw Error('Pacote divergente');
+JS
+  "$node_executable" "$work/node_modules/@remarkkpt/foundry/dist/cli.js" --help >/dev/null || fail 'O programa instalado não arranca; a versão anterior foi preservada.'
+  node - "$work/receipt.json" "$commit" "$digest" <<'JS'
+require('node:fs').writeFileSync(process.argv[2], JSON.stringify({commit:process.argv[3],sha256:process.argv[4]}));
+JS
+  mv "$work" "$target"
+else
+  printf 'A instalação adequada desta versão foi preservada.\n'
+fi
+# Move the old prefix only after the new CLI passed all checks. The EXIT trap
+# restores it if activation fails. Backups are never followed through a symlink.
+if [[ "$update_legacy" == true ]]; then
+  [[ ! -L "$base/backups" ]] || fail 'Destino de backup simbólico; instalação anterior preservada.'
+  mkdir -p "$base/backups"
+  legacy_backup=$(mktemp -d "$base/backups/legacy-XXXXXXXX")
+  if [[ -f "$launcher" ]]; then cp -p "$launcher" "$legacy_backup/foundry"; fi
+  mv "$base/node_modules" "$legacy_backup/node_modules"
+  legacy_moved=true
+  printf 'Backup da instalação anterior: %s\n' "$legacy_backup"
+fi
+# Atomic pointer replacement leaves the previous version untouched on failure.
+node - "$base" "$target" <<'JS'
+const fs = require('node:fs'), path = require('node:path');
+const link = path.join(process.argv[2], '.current-' + process.pid);
+fs.symlinkSync(process.argv[3], link); fs.renameSync(link, path.join(process.argv[2], 'current'));
+JS
+{
+  printf '#!/bin/bash\n# Foundry bootstrap launcher v1\nexec %q %q "$@"\n' "$node_executable" "$base/current/node_modules/@remarkkpt/foundry/dist/cli.js"
+} > "$bin/.foundry-$$"
+chmod 755 "$bin/.foundry-$$"
+mv -f "$bin/.foundry-$$" "$launcher"
+legacy_moved=false
+fi
+case ":$PATH:" in
+  *":$bin:"*) ;;
+  *)
+    confirm 'Preparar o comando foundry nos próximos terminais?' || fail 'Instalação preparada; falta confirmar a preparação do comando foundry. Pode repetir este instalador.'
+    case "${SHELL:-/bin/zsh}" in
+      */zsh) profile="$HOME/.zprofile" ;;
+      */bash) profile="$HOME/.bash_profile" ;;
+      *) fail 'Shell não suportada para preparar o PATH; instalação preservada.' ;;
+    esac
+    [[ ! -L "$profile" ]] || fail 'O perfil da shell é um link simbólico; foi preservado.'
+    line='export PATH="$HOME/.local/bin:$PATH" # Foundry bootstrap'
+    if [[ "$reuse_legacy" == true && "$legacy_launcher" != true ]]; then line='export PATH="$HOME/.local/share/foundry/node_modules/.bin:$PATH" # Foundry bootstrap'; fi
+    if ! grep -Fqx "$line" "$profile" 2>/dev/null; then printf '\n%s\n' "$line" >> "$profile"; fi
+    ;;
+esac
+export PATH="$bin:$PATH"
+printf 'A abrir o assistente Foundry e a seleção de projeto…\n'
+"$launcher" || fail 'O assistente não terminou com sucesso; a instalação foi preservada.'
+printf 'Foundry instalada e assistente terminado. Comando disponível: foundry (novo terminal).\n'

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@remarkkpt/foundry-installer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Minimal macOS bootstrap for the private Foundry distribution",
+  "license": "UNLICENSED",
+  "bin": { "foundry-installer": "install.sh" },
+  "files": ["install.sh", "README.md"],
+  "publishConfig": { "access": "public" }
+}