@tera-system/pro 0.1.0

package/scripts/tera-heartbeat.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * @tera-system/pro — Heartbeat command
+ * --------------------------------------------------------------
+ * Checks in with the license server. If more than HEARTBEAT_DAYS
+ * have passed since the last successful heartbeat, the client
+ * contacts the server to re-validate the license key and detect
+ * revocations.
+ *
+ * Can be invoked:
+ *   - manually        : node scripts/tera-heartbeat.mjs
+ *   - post-install    : called by install.js
+ *   - before commands : called by preflight.mjs (if due)
+ *
+ * Env:
+ *   TERA_LICENSE_API  — API base URL (default https://teranoo.com/api/license)
+ *   TERA_TARGET_DIR   — target workspace
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { readLicenseState, writeLicenseState } from "./lib/license.mjs";
+
+const HEARTBEAT_DAYS = 3;
+const HEARTBEAT_MS = HEARTBEAT_DAYS * 86400000;
+const API_URL = process.env.TERA_LICENSE_API || "https://teranoo.com/api/license";
+
+function resolveTarget() {
+  const args = process.argv.slice(2);
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--target" && args[i + 1]) return path.resolve(args[i + 1]);
+  }
+  return path.resolve(process.env.TERA_TARGET_DIR || process.env.INIT_CWD || process.cwd());
+}
+
+async function serverVerify(licenseKey) {
+  if (!licenseKey) return null;
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 8000);
+    const res = await fetch(`${API_URL}/verify`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ licenseKey }),
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+const target = resolveTarget();
+const stateFile = path.join(target, ".tera", "license.state.json");
+const heartbeatFile = path.join(target, ".tera", "heartbeat.state.json");
+
+(async () => {
+  const now = Date.now();
+
+  // Read previous heartbeat
+  let hb = {};
+  try {
+    hb = JSON.parse(fs.readFileSync(heartbeatFile, "utf8"));
+  } catch {
+    hb = {};
+  }
+  const lastHb = hb.lastHeartbeat ? new Date(hb.lastHeartbeat).getTime() : 0;
+  const due = now - lastHb > HEARTBEAT_MS;
+
+  const license = readLicenseState(stateFile) || {};
+
+  if (!due) {
+    console.log(`✔ heartbeat not due (last: ${hb.lastHeartbeat || "never"}, every ${HEARTBEAT_DAYS}d)`);
+    process.exit(0);
+  }
+
+  if (license.state !== "Active" && license.state !== "Grace") {
+    console.log(`⚠ heartbeat skipped — license state is "${license.state}" (not Active)`);
+    process.exit(0);
+  }
+
+  console.log(`heartbeat due (last ${hb.lastHeartbeat || "never"}) — contacting server...`);
+  const server = await serverVerify(license.licenseKey);
+
+  if (!server) {
+    console.log(`⚠ server unreachable — keeping current license state (will retry in ${HEARTBEAT_DAYS}d)`);
+    fs.mkdirSync(path.dirname(heartbeatFile), { recursive: true });
+    fs.writeFileSync(heartbeatFile, JSON.stringify({
+      lastHeartbeat: new Date().toISOString(),
+      lastResult: "unreachable",
+    }, null, 2));
+    process.exit(2); // non-zero: available but not verified
+  }
+
+  if (server.valid === false) {
+    console.log(`❌ license revoked/invalid by server: ${server.reason || "revoked"}`);
+    writeLicenseState(stateFile, {
+      ...license,
+      state: "Invalid",
+      reason: server.reason || "server-revoked",
+      checkedAt: new Date().toISOString(),
+    });
+    fs.mkdirSync(path.dirname(heartbeatFile), { recursive: true });
+    fs.writeFileSync(heartbeatFile, JSON.stringify({
+      lastHeartbeat: new Date().toISOString(),
+      lastResult: "revoked",
+    }, null, 2));
+    process.exit(1);
+  }
+
+  // Valid — refresh local state
+  writeLicenseState(stateFile, {
+    ...license,
+    state: "Active",
+    reason: "heartbeat-verified",
+    expiresAt: server.expiresAt || license.expiresAt || null,
+    checkedAt: new Date().toISOString(),
+  });
+  fs.mkdirSync(path.dirname(heartbeatFile), { recursive: true });
+  fs.writeFileSync(heartbeatFile, JSON.stringify({
+    lastHeartbeat: new Date().toISOString(),
+    lastResult: "ok",
+    expiresAt: server.expiresAt || null,
+  }, null, 2));
+
+  console.log(`✔ heartbeat verified — state=Active (expires ${server.expiresAt || "?"})`);
+  process.exit(0);
+})().catch((err) => {
+  console.error(`❌ heartbeat error: ${err.message}`);
+  process.exit(1);
+});

package/scripts/tera-license.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// @tera/core license CLI — issue & verify license keys (SCP-005)
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { issueLicenseKey, assessLicenseState, readLicenseState, STATES } from "./lib/license.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DEV_KEY = path.join(__dirname, "..", "license", "dev", "dev-private-key.pem");
+
+function usage() {
+  console.log(`Usage:
+  tera-license gen --tier <basic|premium> --project <name> --expires <YYYY-MM-DD> [--seats N]
+       (private key: env TERA_LICENSE_PRIVATE or the dev key under license/dev/)
+  tera-license check [--key <licenseKey> | --state-file <path>]
+       (or env TERA_LICENSE_KEY)`);
+}
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+function flag(name) {
+  const i = args.indexOf(name);
+  return i >= 0 && args[i + 1] ? args[i + 1] : undefined;
+}
+
+if (cmd === "gen") {
+  const tier = flag("--tier") || "basic";
+  const project = flag("--project");
+  const expires = flag("--expires");
+  const seats = flag("--seats") ? Number(flag("--seats")) : 1;
+  if (!project || !expires) {
+    usage();
+    process.exit(1);
+  }
+  const privatePem = process.env.TERA_LICENSE_PRIVATE || fs.readFileSync(DEV_KEY, "utf8");
+  const key = issueLicenseKey(
+    { tier, project, issuedAt: new Date().toISOString(), expiresAt: new Date(expires).toISOString(), seats },
+    privatePem
+  );
+  console.log(key);
+} else if (cmd === "check") {
+  let key = flag("--key");
+  if (!key) {
+    const stateFile = flag("--state-file");
+    if (stateFile) {
+      const st = readLicenseState(stateFile);
+      key = st && st.licenseKey;
+      if (!key) {
+        console.log(JSON.stringify({ state: STATES.UNLICENSED, reason: "no-key-trial" }, null, 2));
+        process.exit(0);
+      }
+    } else {
+      key = process.env.TERA_LICENSE_KEY;
+    }
+  }
+  if (!key) {
+    console.log(JSON.stringify({ state: STATES.UNLICENSED, reason: "no-key-trial" }, null, 2));
+    process.exit(0);
+  }
+  console.log(JSON.stringify(assessLicenseState(key), null, 2));
+} else {
+  usage();
+}

package/scripts/tera-sync.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * @tera-system/pro — Sync command
+ * --------------------------------------------------------------
+ * Downloads the signed core bundle from the remote server (or a
+ * configured URL), verifies its Ed25519 signature, validates every
+ * file hash, and applies the files into the target workspace.
+ *
+ * Usage:
+ *   node scripts/tera-sync.mjs [--target <dir>] [--url <bundleUrl>]
+ *
+ * Env:
+ *   TERA_SYNC_URL     — bundle URL (default: https://teranoo.com/api/tera-system/bundle)
+ *   TERA_TARGET_DIR   — target workspace (fallback: INIT_CWD / cwd)
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { verifyBundle, applyBundle } from "./lib/bundle.mjs";
+
+const DEFAULT_URL = "https://teranoo.com/api/tera-system/bundle";
+
+function resolveArgs() {
+  const args = process.argv.slice(2);
+  let target = process.env.TERA_TARGET_DIR || process.env.INIT_CWD || process.cwd();
+  let url = process.env.TERA_SYNC_URL || DEFAULT_URL;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--target" && args[i + 1]) target = path.resolve(args[i + 1]);
+    if (args[i] === "--url" && args[i + 1]) url = args[i + 1];
+    if (args[i] === "--help") {
+      console.log("Usage: node scripts/tera-sync.mjs [--target <dir>] [--url <bundleUrl>]");
+      process.exit(0);
+    }
+  }
+  return { target: path.resolve(target), url };
+}
+
+async function downloadBundle(url) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 15000);
+  try {
+    const res = await fetch(url, { signal: controller.signal });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const bundle = await res.json();
+    clearTimeout(timeout);
+    return bundle;
+  } catch (err) {
+    clearTimeout(timeout);
+    throw new Error(`download-failed: ${err.message}`);
+  }
+}
+
+const { target, url } = resolveArgs();
+const syncStateFile = path.join(target, ".tera", "sync.state.json");
+
+(async () => {
+  console.log(`\n@tera-system/pro — sync`);
+  console.log(`  target : ${target}`);
+  console.log(`  url    : ${url}\n`);
+
+  let bundle;
+  try {
+    bundle = await downloadBundle(url);
+  } catch (err) {
+    console.log(`❌ ${err.message}`);
+    console.log("  The system will retry later (background) or on next install.");
+    fs.mkdirSync(path.dirname(syncStateFile), { recursive: true });
+    fs.writeFileSync(
+      syncStateFile,
+      JSON.stringify({
+        status: "pending",
+        lastError: err.message,
+        lastAttempt: new Date().toISOString(),
+      }, null, 2)
+    );
+    process.exit(1);
+  }
+
+  // Verify signature + hashes
+  const verification = verifyBundle(bundle);
+  if (!verification.ok) {
+    console.log(`❌ Bundle verification failed: ${verification.reason}`);
+    fs.mkdirSync(path.dirname(syncStateFile), { recursive: true });
+    fs.writeFileSync(syncStateFile, JSON.stringify({
+      status: "failed",
+      reason: verification.reason,
+      lastAttempt: new Date().toISOString(),
+    }, null, 2));
+    process.exit(1);
+  }
+
+  console.log(`✔ Signature verified (contentSha256=${verification.contentSha256.slice(0, 16)}...)`);
+  console.log(`✔ Bundle version  : ${verification.packageVersion} (created ${verification.createdAt?.slice(0, 10)})`);
+
+  // Apply files
+  const result = applyBundle(bundle, target);
+  console.log(`✔ Files applied    : ${result.applied}`);
+  if (result.errors.length) {
+    console.log(`⚠ Errors           : ${result.errors.join(", ")}`);
+  }
+
+  // Record sync state
+  fs.mkdirSync(path.dirname(syncStateFile), { recursive: true });
+  fs.writeFileSync(syncStateFile, JSON.stringify({
+    status: "completed",
+    packageVersion: verification.packageVersion,
+    contentSha256: verification.contentSha256,
+    filesApplied: result.applied,
+    syncedAt: new Date().toISOString(),
+  }, null, 2));
+
+  console.log(`✔ Sync state       : .tera/sync.state.json`);
+  console.log("\n✔ sync complete");
+})().catch((err) => {
+  console.error(`❌ unexpected error: ${err.message}`);
+  process.exit(1);
+});

package/tools/tera-clean.ps1

@@ -0,0 +1,97 @@
+<#
+  Tera Clean - release-readiness whitespace cleaner for Tera-managed roots.
+  Finds and removes trailing whitespace and extra blank lines at EOF so that
+  the repo passes `git diff --check` (the gate enforced by tera-update.ps1).
+
+  Scope: only Tera-managed roots: .opencode/, tera-system/, tera-workshop/.
+  Mode:
+    -DryRun  : report only, no writes (default)
+    (no -DryRun) : clean files in place
+
+  Source of truth: tera-system/TERA_DISTRIBUTION_POLICY.md (SCP-2026-08-15-010)
+#>
+[CmdletBinding()]
+param(
+    [string]$RepoPath = (Get-Location).Path,
+    [switch]$DryRun
+)
+
+Set-StrictMode -Version 5
+$ErrorActionPreference = 'Stop'
+
+function Test-TrailingWhitespace([string]$Text) {
+    # [ \t]+ at end of line (optional \r before \n for CRLF)
+    return $Text -match '(?m)[ \t]+\r?$'
+}
+
+function Test-ExtraBlankAtEof([string]$Text) {
+    # more than one line terminator at EOF => extra blank lines
+    return $Text -match '(\r?\n){2,}$'
+}
+
+function Get-LineEnding([string]$Text) {
+    if ($Text.Contains("`r`n")) { return "`r`n" }
+    return "`n"
+}
+
+$RepoPath = [System.IO.Path]::GetFullPath($RepoPath)
+if (-not (Test-Path -LiteralPath $RepoPath -PathType Container)) { throw "RepoPath does not exist: $RepoPath" }
+$gitRoot = (& git -C $RepoPath rev-parse --show-toplevel 2>$null).Trim()
+if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($gitRoot)) { throw "RepoPath must be a Git repository." }
+$gitRoot = [System.IO.Path]::GetFullPath($gitRoot)
+
+$binaryExt = @('.png','.jpg','.jpeg','.gif','.ico','.bmp','.woff','.woff2','.ttf','.otf','.node')
+$managedRoots = @('.opencode', 'tera-system', 'tera-workshop')
+
+$tracked = @(& git -C $RepoPath ls-files)
+$targets = @()
+foreach ($file in $tracked) {
+    $isManaged = $false
+    foreach ($root in $managedRoots) {
+        if ($file -eq $root -or $file.StartsWith($root + '/')) { $isManaged = $true; break }
+    }
+    if (-not $isManaged) { continue }
+    $ext = [System.IO.Path]::GetExtension($file).ToLowerInvariant()
+    if ($binaryExt -contains $ext) { continue }
+    $full = Join-Path $gitRoot ($file -replace '/', '\')
+    if (-not (Test-Path -LiteralPath $full)) { continue }
+    $targets += $file
+}
+
+$changed = @()
+foreach ($file in $targets) {
+    $full = Join-Path $gitRoot ($file -replace '/', '\')
+    $raw = [System.IO.File]::ReadAllText($full)
+    $hasTrailing = Test-TrailingWhitespace $raw
+    $hasExtraBlank = Test-ExtraBlankAtEof $raw
+    if (-not ($hasTrailing -or $hasExtraBlank)) { continue }
+
+    if ($DryRun) {
+        $changed += [pscustomobject]@{ File = $file; Trailing = $hasTrailing; ExtraBlank = $hasExtraBlank }
+        continue
+    }
+
+    $eol = Get-LineEnding $raw
+    $lines = $raw -split '\r?\n'
+    $clean = @()
+    foreach ($ln in $lines) { $clean += $ln -replace '[ \t]+$', '' }
+    # remove trailing empty lines but keep exactly one final line terminator
+    while ($clean.Count -gt 1 -and $clean[$clean.Count - 1].Trim() -eq '') {
+        $clean = $clean[0..($clean.Count - 2)]
+    }
+    $newText = ($clean -join $eol) + $eol
+    if ($newText -ne $raw) {
+        [System.IO.File]::WriteAllText($full, $newText, (New-Object System.Text.UTF8Encoding $false))
+        $changed += [pscustomobject]@{ File = $file; Trailing = $hasTrailing; ExtraBlank = $hasExtraBlank }
+    }
+}
+
+if ($DryRun) {
+    Write-Host "Tera Clean [DRY RUN] - files that would be changed: $($changed.Count)"
+    $changed | ForEach-Object { Write-Host ("  {0}  (trailing={1}, extraBlank={2})" -f $_.File, $_.Trailing, $_.ExtraBlank) }
+    Write-Host "Run without -DryRun to apply."
+} else {
+    Write-Host "Tera Clean - changed files: $($changed.Count)"
+    $changed | ForEach-Object { Write-Host ("  {0}" -f $_.File) }
+    Write-Host "Next: git add -A && git diff --cached --check"
+}

package/tools/tera-fetch.ps1

@@ -0,0 +1,165 @@
+<#
+  Tera Fetch — fetch release metadata, check for updates, or build a verified
+  release package from the origin repository.
+  Modes:
+    -List        : list available version tags from the origin repository
+    -Check       : compare installed version (lock.json) with latest from origin
+    -Fetch       : create a verified release package (Manifest + SHA256SUMS)
+                   from the exact tag via tera-release.ps1
+  Source of truth: tera-system/TERA_DISTRIBUTION_POLICY.md (SCP-2026-08-15-009, 012)
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$RepositoryUrl,
+
+    [switch]$List,
+
+    [switch]$Check,
+
+    [string]$Version,
+
+    [string]$OutPath,
+
+    [string]$RepoPath = (Get-Location).Path,
+
+    [ValidateSet('stable', 'beta')]
+    [string]$Channel = 'stable',
+
+    [string]$CachePath
+)
+
+Set-StrictMode -Version 5
+# Continue وليس Stop: هذا السكربت يعتمد على فحوص $LASTEXITCODE الصريحة بعد كل
+# استدعاء git، و stderr الطبيعي لـ git (مثل رسائل التقدم) يجب ألا يوقف التنفيذ.
+$ErrorActionPreference = 'Continue'
+
+function Fail([string]$Message) {
+    throw $Message
+}
+
+# مقارنة إصدارات رقمية X.Y.Z — ترجع 1 إذا a أحدث، -1 إذا b أحدث، 0 إذا متساويان
+function Compare-TeraVersion([string]$a, [string]$b) {
+    $aParts = ($a -replace '^tera-v', '').Split('.')
+    $bParts = ($b -replace '^tera-v', '').Split('.')
+    for ($i = 0; $i -lt [Math]::Max($aParts.Count, $bParts.Count); $i++) {
+        $pa = 0; $pb = 0
+        if ($i -lt $aParts.Count) { [void][int]::TryParse($aParts[$i], [ref]$pa) }
+        if ($i -lt $bParts.Count) { [void][int]::TryParse($bParts[$i], [ref]$pb) }
+        if ($pa -gt $pb) { return 1 }
+        if ($pa -lt $pb) { return -1 }
+    }
+    return 0
+}
+
+# جلب قائمة إصدارات tera-vX.Y.Z من الأصل (مشترك بين List و Check)
+function Get-OriginVersions([string]$Url) {
+    $lines = @(& git ls-remote --tags $Url 2>$null)
+    if ($LASTEXITCODE -ne 0) { Fail "Could not reach origin repository: $Url" }
+    $versions = New-Object System.Collections.Generic.List[string]
+    foreach ($line in $lines) {
+        if ($line -match 'refs/tags/(tera-v[0-9]+\.[0-9]+\.[0-9]+)(\^\{\})?$') {
+            $versions.Add($matches[1])
+        }
+    }
+    $sorted = @($versions | Sort-Object -Unique)
+    return , $sorted
+}
+
+#---------------------------------------------------------------------
+# 1. List mode — عرض الإصدارات المتاحة من المستودع الأصلي
+#---------------------------------------------------------------------
+if ($List) {
+    $versions = Get-OriginVersions $RepositoryUrl
+    if ($versions.Count -eq 0) {
+        Write-Host "No tera-vX.Y.Z tags found in: $RepositoryUrl"
+    } else {
+        Write-Host "Available Tera versions (from origin):"
+        $versions | ForEach-Object { Write-Host "  $_" }
+    }
+    return
+}
+
+#---------------------------------------------------------------------
+# 2. Check mode — هل يوجد إصدار أحدث من المثبت؟
+#---------------------------------------------------------------------
+if ($Check) {
+    $versions = Get-OriginVersions $RepositoryUrl
+    if ($versions.Count -eq 0) {
+        Write-Host "No tera-vX.Y.Z tags found in: $RepositoryUrl"
+        return
+    }
+    $latest = $versions[-1]
+
+    $lockPath = Join-Path $RepoPath '.tera\lock.json'
+    $installed = $null
+    if (Test-Path -LiteralPath $lockPath) {
+        try {
+            $lock = Get-Content -LiteralPath $lockPath -Raw | ConvertFrom-Json
+            if ($lock.tag) { $installed = [string]$lock.tag }
+        } catch {
+            Write-Warning "lock.json unreadable at $lockPath — treating as no installation."
+        }
+    }
+
+    if (-not $installed) {
+        Write-Host "No prior installation detected in $RepoPath."
+        Write-Host "Latest available: $latest"
+        Write-Host "Install with: tera-update.ps1 -Version $latest -Mode Apply -Initialize -RepositoryUrl `"$RepositoryUrl`""
+        return
+    }
+
+    $cmp = Compare-TeraVersion $installed $latest
+    if ($cmp -ge 0) {
+        Write-Host "You are up to date: $installed (latest in origin: $latest)"
+    } else {
+        Write-Host "Update available!"
+        Write-Host "  Installed: $installed"
+        Write-Host "  Latest:    $latest"
+        Write-Host "Upgrade with: tera-update.ps1 -Version $latest -Mode Apply -RepositoryUrl `"$RepositoryUrl`""
+    }
+    return
+}
+
+#---------------------------------------------------------------------
+# 3. Fetch mode — بناء حزمة إصدار موثقة من المستودع الأصلي
+#---------------------------------------------------------------------
+if (-not $Version) { Fail 'Fetch mode requires -Version (e.g. tera-v2.5.0).' }
+if (-not $OutPath) { Fail 'Fetch mode requires -OutPath.' }
+
+if (-not $CachePath) {
+    $CachePath = Join-Path $env:LOCALAPPDATA 'Tera\release-cache'
+}
+New-Item -ItemType Directory -Path $CachePath -Force | Out-Null
+
+# إنشاء استنساخ موقت (shallow) عند الـ Tag المطلوب من المستودع الأصلي
+$tempCheckout = Join-Path $CachePath ("checkout-" + [guid]::NewGuid().ToString('N'))
+try {
+    $null = & git init $tempCheckout 2>$null
+    if ($LASTEXITCODE -ne 0) { Fail "Could not initialize temp checkout." }
+    $null = & git -C $tempCheckout remote add origin $RepositoryUrl 2>$null
+    if ($LASTEXITCODE -ne 0) { Fail "Could not add origin remote: $RepositoryUrl" }
+    $refspec = ('refs/tags/{0}:refs/tags/{0}' -f $Version)
+    $null = & git -C $tempCheckout fetch --depth 1 origin $refspec 2>$null
+    if ($LASTEXITCODE -ne 0) { Fail "Could not fetch tag $Version from origin." }
+    $null = & git -C $tempCheckout checkout --quiet $Version 2>$null
+    if ($LASTEXITCODE -ne 0) { Fail "Could not checkout tag $Version." }
+
+    $commit = (& git -C $tempCheckout rev-list -n 1 $Version 2>$null).Trim()
+    if ($commit -notmatch '^[0-9a-fA-F]{40}$') { Fail "Could not resolve commit for $Version." }
+
+    Write-Host "Fetched $Version from origin (commit $commit)."
+    Write-Host "Building verified release package via tera-release.ps1 ..."
+
+    $releaseBuilder = Join-Path (Split-Path -Parent $MyInvocation.MyCommand.Path) 'tera-release.ps1'
+    & $releaseBuilder -Version $Version -Tag $Version -Channel $Channel -RepoPath $tempCheckout -OutputPath $OutPath
+    if ($LASTEXITCODE -ne 0) { Fail "tera-release.ps1 failed for $Version." }
+
+    Write-Host "Fetched and built verified package: $OutPath"
+    Write-Host "Next: run tera-update.ps1 -SourcePath $OutPath"
+}
+finally {
+    if (Test-Path -LiteralPath $tempCheckout) {
+        Remove-Item -LiteralPath $tempCheckout -Recurse -Force -ErrorAction SilentlyContinue
+    }
+}

package/tools/tera-release.ps1

@@ -0,0 +1,96 @@
+<#
+  Build a deterministic Tera release directory from the exact Git tag.
+  The working tree is never used as the release content.
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$Version,
+
+    [string]$Tag,
+
+    [ValidateSet('stable', 'beta')]
+    [string]$Channel = 'stable',
+
+    [Parameter(Mandatory = $true)]
+    [string]$OutputPath,
+
+    [string]$RepoPath = (Get-Location).Path
+)
+
+Set-StrictMode -Version 5
+$ErrorActionPreference = 'Stop'
+
+if (-not $Tag) { $Tag = "tera-v$Version" }
+$RepoPath = [System.IO.Path]::GetFullPath($RepoPath)
+$OutputPath = [System.IO.Path]::GetFullPath($OutputPath)
+if (-not (Test-Path -LiteralPath $RepoPath -PathType Container)) { throw "RepoPath not found: $RepoPath" }
+$top = (git -C $RepoPath rev-parse --show-toplevel 2>$null).Trim()
+if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($top)) { throw 'RepoPath must be a Git repository.' }
+$commit = (git -C $RepoPath rev-list -n 1 "$Tag^{commit}" 2>$null).Trim()
+if ($LASTEXITCODE -ne 0 -or $commit -notmatch '^[0-9a-fA-F]{40}$') { throw "Tag does not resolve to a full commit: $Tag" }
+$normalizedVersion = ($Version -replace '^tera-', '') -replace '^v', ''
+
+# التحقق من اتساق Version مع Tag — رفض الحزم المتناقضة
+$expectedTag = "tera-v$normalizedVersion"
+if ($Tag -ne $expectedTag) {
+    throw "Tag $Tag does not match Version $Version (expected $expectedTag)."
+}
+
+if (Test-Path -LiteralPath $OutputPath) {
+    $children = @(Get-ChildItem -LiteralPath $OutputPath -Force)
+    if ($children.Count -gt 0) { throw "OutputPath must be empty: $OutputPath" }
+} else {
+    New-Item -ItemType Directory -Path $OutputPath -Force | Out-Null
+}
+
+$tempRoot = Join-Path ([System.IO.Path]::GetTempPath()) ("tera-release-" + [guid]::NewGuid().ToString('N'))
+$archivePath = Join-Path $tempRoot 'tag.zip'
+$snapshotRoot = Join-Path $tempRoot 'snapshot'
+$managedRoots = @('.opencode', 'tera-system', 'tera-workshop')
+$files = New-Object System.Collections.Generic.List[string]
+
+try {
+    New-Item -ItemType Directory -Path $tempRoot -Force | Out-Null
+    $null = & git -C $RepoPath archive --format=zip "--output=$archivePath" $Tag 2>$null
+    if ($LASTEXITCODE -ne 0 -or -not (Test-Path -LiteralPath $archivePath -PathType Leaf)) {
+        throw "Could not archive exact Git tag: $Tag"
+    }
+    Expand-Archive -LiteralPath $archivePath -DestinationPath $snapshotRoot -Force
+
+    foreach ($root in $managedRoots) {
+        $sourceRoot = Join-Path $snapshotRoot $root
+        if (-not (Test-Path -LiteralPath $sourceRoot -PathType Container)) { continue }
+        foreach ($file in Get-ChildItem -LiteralPath $sourceRoot -File -Recurse) {
+            $relative = ($file.FullName.Substring($snapshotRoot.Length + 1) -replace '\\', '/')
+            $target = Join-Path $OutputPath $relative
+            $targetDir = Split-Path -Parent $target
+            if (-not (Test-Path -LiteralPath $targetDir)) { New-Item -ItemType Directory -Path $targetDir -Force | Out-Null }
+            Copy-Item -LiteralPath $file.FullName -Destination $target -Force
+            $files.Add($relative)
+        }
+    }
+    if ($files.Count -eq 0) { throw 'No managed files found in the tagged snapshot.' }
+
+    $manifest = [ordered]@{
+        version = $normalizedVersion
+        tag = $Tag
+        commit = $commit
+        channel = $Channel
+        files = @($files | Sort-Object)
+    }
+    $manifest | ConvertTo-Json -Depth 5 | Set-Content -LiteralPath (Join-Path $OutputPath 'TERA_RELEASE_MANIFEST.json') -Encoding UTF8
+
+    $sumLines = New-Object System.Collections.Generic.List[string]
+    foreach ($relative in ($files | Sort-Object)) {
+        $hash = (Get-FileHash -LiteralPath (Join-Path $OutputPath $relative) -Algorithm SHA256).Hash.ToLowerInvariant()
+        $sumLines.Add("$hash  $relative")
+    }
+    $sumLines | Set-Content -LiteralPath (Join-Path $OutputPath 'SHA256SUMS') -Encoding ASCII
+}
+finally {
+    if (Test-Path -LiteralPath $tempRoot) { Remove-Item -LiteralPath $tempRoot -Recurse -Force -ErrorAction SilentlyContinue }
+}
+
+Write-Host "Release created from exact tag: $OutputPath"
+Write-Host "Tag=$Tag Commit=$commit Channel=$Channel Files=$($files.Count)"