@timekast/factory 1.6.0 → 1.7.0

package/dist/commands/add.js

@@ -87,6 +87,9 @@ export async function runAdd(flags = { core: false, full: false }) {
             verify: false,
             commit: false,
             noCommit: false,
+            // A legacy `add` redirect is never a beta channel operation.
+            beta: false,
+            stable: false,
         });
         return;
     }

package/dist/commands/doctor.js

@@ -22,6 +22,7 @@ import { collectClaudePaths } from '../lib/claude-paths.js';
 import { CLAUDE_MD_FILE } from '../lib/constants.js';
 import { hasLockfile, normalizeThenHash, readLockfile } from '../lib/lockfile.js';
 import { detectRepo } from '../lib/repo-detection.js';
+import { BETA_BANNER } from './status.js';
 /** Matches a flat always-on rule file shipped by the kit (`.claude/rules/<name>.md`). */
 const RULE_PATH_RE = /^\.claude\/rules\/[^/]+\.md$/;
 /**
@@ -112,9 +113,12 @@ export function computeDoctor(deps = {}) {
             claudeMdMissing: false,
             a1Warning: A1_WARNING,
             noLockfile: true,
+            beta: false,
         };
     }
     const lock = readLockfile(rootDir);
+    // Beta channel marker (BETA-002). Absent / non-boolean → false (back-compat).
+    const beta = lock.beta === true;
     const manifestPaths = new Set(lock.files.map((f) => f.path));
     // Orphans: files under `.claude/` on disk that the manifest does not track.
     const claudePaths = collectClaudePaths(rootDir);
@@ -162,6 +166,7 @@ export function computeDoctor(deps = {}) {
         claudeMdMissing,
         a1Warning: A1_WARNING,
         noLockfile: false,
+        beta,
     };
 }
 /** Render the doctor result to the console. The A1 notice is ALWAYS last. */
@@ -173,6 +178,11 @@ function renderDoctor(result) {
         console.log(`\n${result.a1Warning}`);
         return;
     }
+    // Beta banner first (BETA-005): the most important state when on a pre-release
+    // brain. Shown regardless of orphans/conflicts so it never gets buried.
+    if (result.beta) {
+        console.log(BETA_BANNER);
+    }
     if (result.orphans.length === 0 &&
         result.conflicts.length === 0 &&
         result.unimportedRules.length === 0 &&

package/dist/commands/status.js

@@ -17,6 +17,14 @@
 import { execa } from 'execa';
 import { FACTORY_REPO } from '../lib/constants.js';
 import { hasLockfile, readLockfile } from '../lib/lockfile.js';
+import { compare } from '../lib/semver.js';
+/**
+ * The BETA channel banner (BETA-005). Emitted by `status` and `doctor` when the
+ * lockfile is on the beta channel (`lockfile.beta === true`) so the dev always
+ * sees they are on a pre-release brain and how to leave the channel. Exported so
+ * the tests assert on the exact rendered text (no magic string in the spec).
+ */
+export const BETA_BANNER = '⚠️  cerebro BETA — corre `factory update --stable` para salir del canal';
 /**
  * Query the Factory repo for the latest published release, IGNORING prereleases
  * (`-rc`, `-test`, etc.) so a release candidate is never reported as latest.
@@ -52,24 +60,6 @@ async function fetchLatestRelease() {
 function stripVersionPrefix(tag) {
     return tag.startsWith('v') ? tag.slice(1) : tag;
 }
-/**
- * Compare two semver-ish strings. Returns 1 when `a` > `b`, -1 when `a` < `b`,
- * 0 when equal. Non-numeric / malformed segments compare as 0 so a parse
- * surprise never flips `hasUpdate` to a false positive.
- */
-function compareVersions(a, b) {
-    const pa = a.split('.').map((n) => Number.parseInt(n, 10) || 0);
-    const pb = b.split('.').map((n) => Number.parseInt(n, 10) || 0);
-    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
-        const da = pa[i] ?? 0;
-        const db = pb[i] ?? 0;
-        if (da > db)
-            return 1;
-        if (da < db)
-            return -1;
-    }
-    return 0;
-}
 /**
  * Compute the status result. Pure given its inputs — the only side effect is the
  * lockfile read (FS), and `fetchLatest` (network). Both are graceful: a missing
@@ -86,6 +76,7 @@ export async function computeStatus(deps = {}) {
             hasUpdate: false,
             noLockfile: true,
             networkError: false,
+            beta: false,
         };
     }
     const lock = readLockfile(rootDir);
@@ -94,6 +85,8 @@ export async function computeStatus(deps = {}) {
     // the top-level `factoryVersion` is the birth stamp. A legacy lockfile without
     // a birth stamp degrades to null (it is reported as "unknown", never crashes).
     const factoryVersion = lock.factoryVersion ?? null;
+    // Beta channel marker (BETA-002). Absent / non-boolean → false (back-compat).
+    const beta = lock.beta === true;
     const latest = await fetchLatest();
     if (latest === null) {
         return {
@@ -103,15 +96,22 @@ export async function computeStatus(deps = {}) {
             hasUpdate: false,
             noLockfile: false,
             networkError: true,
+            beta,
         };
     }
     return {
         installed,
         factoryVersion,
         latest,
-        hasUpdate: compareVersions(latest, installed) > 0,
+        // `latest` is the newest STABLE release (prereleases are filtered out by
+        // `fetchLatest`). With the BETA-001 comparator, a beta install newer than the
+        // latest stable (e.g. installed `10.9.0-beta.0`, latest `10.8.0`) yields
+        // `compare('10.8.0', '10.9.0-beta.0') < 0` → hasUpdate:false: there is no
+        // stable update to offer, so the render does not contradict the BETA banner.
+        hasUpdate: compare(latest, installed) > 0,
         noLockfile: false,
         networkError: false,
+        beta,
     };
 }
 /** Render the status result to the console. */
@@ -121,6 +121,11 @@ function renderStatus(result) {
         console.log('Ejecuta `factory:update` para inicializar el tracking de versión.');
         return;
     }
+    // Beta banner first so it leads the report — it is the most important state
+    // when on a pre-release brain (BETA-005).
+    if (result.beta) {
+        console.log(BETA_BANNER);
+    }
     console.log(`Instalado: v${result.installed}`);
     if (result.factoryVersion) {
         console.log(`Sello de nacimiento (factoryVersion): v${result.factoryVersion}`);
@@ -133,7 +138,9 @@ function renderStatus(result) {
     if (result.hasUpdate) {
         console.log('⬆ Actualización disponible — ejecuta factory:update');
     }
-    else {
+    else if (!result.beta) {
+        // Suppress "estás en la última versión" on the beta channel: with no stable
+        // update to offer, that line would contradict the BETA banner above (B3b).
         console.log('✔ Estás en la última versión.');
     }
 }

package/dist/commands/update.js

@@ -48,7 +48,7 @@ import { diffLockfiles, hasLockfile, normalizeThenHash, planAutoRegister, readLo
 import { detectProfile, insertFactoryUpdateScript, setAgentKitVersion, } from '../lib/package-json.js';
 import { runPreflight } from '../lib/preflight.js';
 import { detectRepo } from '../lib/repo-detection.js';
-import { downloadProfileTarball, stageProfileTarball } from '../lib/unpack.js';
+import { downloadBetaProfileTarball, downloadProfileTarball, stageProfileTarball, } from '../lib/unpack.js';
 /** Parse `update`'s argv slice into flags. Unknown flags are ignored here. */
 export function parseUpdateFlags(argv) {
     return {
@@ -60,6 +60,8 @@ export function parseUpdateFlags(argv) {
         full: argv.includes('--full'),
         commit: argv.includes('--commit'),
         noCommit: argv.includes('--no-commit'),
+        beta: argv.includes('--beta'),
+        stable: argv.includes('--stable'),
     };
 }
 /** Default acquire: download the sticky-profile tarball, stage + validate it. */
@@ -70,6 +72,20 @@ async function acquireFromRelease(profile) {
     const manifest = validateStagedManifest(stagedDir, manifestRaw);
     return { stagedDir, manifest, tmpRoot };
 }
+/**
+ * Beta acquire: parallel to {@link acquireFromRelease} but resolves the latest
+ * `-beta.N` pre-release (BETA-003's `downloadBetaProfileTarball`) instead of the
+ * `gh`-latest stable. The staged tarball passes through the SAME engine (diff /
+ * apply / lockfile) — only the SOURCE differs. The `-beta.N` version lands in the
+ * lockfile via the manifest; `stampBeta` adds `beta:true` at the write step.
+ */
+async function acquireFromBeta(profile) {
+    const tmpRoot = mkdtempSync(path.join(tmpdir(), 'tk-update-beta-'));
+    const tarball = await downloadBetaProfileTarball(profile, tmpRoot);
+    const { stagedDir, manifestRaw } = await stageProfileTarball(tarball, tmpRoot);
+    const manifest = validateStagedManifest(stagedDir, manifestRaw);
+    return { stagedDir, manifest, tmpRoot };
+}
 /**
  * Hash the disk content (normalized) of every path in `paths` that exists.
  * A missing file is simply absent from the returned map.
@@ -223,9 +239,21 @@ async function runResume(rootDir, flags) {
     // clean apply), so it carries the birth stamp to preserve. A legacy resume (no
     // prior lockfile) seals the birth at the persisted manifest's version.
     const priorLock = hasLockfile(rootDir) ? readLockfile(rootDir) : undefined;
+    // Channel re-stamp (Edge-1): an interrupted beta update would otherwise lose
+    // `beta:true`, since `state.newManifest` is the stable-shaped embedded manifest.
+    // The channel is recovered from the persisted state (the fresh run stamps
+    // `beta:true` into it for a `--beta` update) OR, as a fallback for a state
+    // persisted before this field existed, from the prior lockfile's channel. An
+    // explicit `--stable` resume always exits the channel (the flag is the intent),
+    // so it overrides the fallback. A stable resume has no signal → `beta` omitted.
+    const resumeBeta = !flags.stable && (state.newManifest.beta === true || priorLock?.beta === true);
     const newLock = priorLock
         ? { ...state.newManifest, factoryVersion: priorLock.factoryVersion ?? priorLock.version }
         : { ...state.newManifest, factoryVersion: state.newManifest.version };
+    if (resumeBeta)
+        newLock.beta = true;
+    else
+        delete newLock.beta;
     applyPlan(rootDir, state.stagedDir, state.plan, state.backupDir);
     writeLockfile(rootDir, newLock);
     clearUpdateState(rootDir);
@@ -245,6 +273,18 @@ async function runResume(rootDir, flags) {
 function stampBirth(oldLock, newManifest) {
     return { ...newManifest, factoryVersion: oldLock.factoryVersion ?? oldLock.version };
 }
+/**
+ * Stamp the beta channel onto the new lockfile. COMPOSES `stampBirth` (never
+ * replaces it): the birth seal is preserved exactly as for a stable update, then
+ * `beta: true` is layered on top. A beta→beta update therefore keeps
+ * `factoryVersion` frozen (it flows through `stampBirth`) AND re-marks the channel
+ * (H4). A STABLE update uses `stampBirth` directly: the stable manifest carries no
+ * `beta`, so the field is simply absent from the new lockfile — the channel is
+ * cleared by omission (no explicit `beta:false` needed).
+ */
+function stampBeta(oldLock, newManifest) {
+    return { ...stampBirth(oldLock, newManifest), beta: true };
+}
 /** Warn (never fail) when package.json holds a divergent factory:update value. */
 function warnOnScriptConflict(action, _pkgPath) {
     if (action === 'conflict') {
@@ -384,6 +424,9 @@ export async function runUpdate(flags, deps = {}) {
     if (flags.core && flags.full) {
         throw new CLIError('No puedes combinar `--core` con `--full`.');
     }
+    if (flags.beta && flags.stable) {
+        throw new CLIError('No puedes combinar `--beta` con `--stable`.');
+    }
     // --verify and --resume short-circuit (no download).
     if (flags.verify) {
         runVerify(rootDir);
@@ -415,6 +458,10 @@ export async function runUpdate(flags, deps = {}) {
     }
     else {
         oldLock = readLockfile(rootDir);
+        // Channel-change guard (B3a): a plain/stable update over a beta lockfile must
+        // be confirmed (or rejected headless) BEFORE any download. Runs after the
+        // lockfile read (it needs `oldLock.beta`) and before acquire.
+        await guardChannelChange(oldLock, flags);
         if (flags.full && oldLock.profile === PROFILES.core) {
             profile = PROFILES.full; // cross-grade core → full (additive)
         }
@@ -426,7 +473,10 @@ export async function runUpdate(flags, deps = {}) {
             profile = oldLock.profile; // sticky (--full on full / --core on core = refresh)
         }
     }
-    const acquire = deps.acquire ?? acquireFromRelease;
+    // Acquire source: `--beta` pulls the latest `-beta.N` pre-release; everything
+    // else pulls the latest stable. The injected `deps.acquire` (tests) wins over
+    // both. Both sources feed the SAME engine downstream.
+    const acquire = deps.acquire ?? (flags.beta ? acquireFromBeta : acquireFromRelease);
     const { stagedDir, manifest, tmpRoot } = await acquire(profile);
     try {
         // Guard: the downloaded tarball must match the resolved profile. A mispublished
@@ -464,12 +514,18 @@ export async function runUpdate(flags, deps = {}) {
         const plan = buildPlan(diff, theirsConflicts);
         const backupDir = defaultBackupDir(tmpRoot);
         // Persist resume state BEFORE applying, so a crash mid-apply is recoverable
-        // without re-downloading (design §7.5).
-        writeUpdateState(rootDir, { stagedDir, backupDir, plan, newManifest: manifest });
+        // without re-downloading (design §7.5). The CHANNEL is persisted here (Edge-1):
+        // `--beta` stamps `beta:true` onto the state's manifest so a `--resume` of an
+        // interrupted beta keeps the channel even when the on-disk lockfile predates it
+        // (first entry from a stable lockfile, where `priorLock.beta` is absent).
+        const stateManifest = flags.beta ? { ...manifest, beta: true } : manifest;
+        writeUpdateState(rootDir, { stagedDir, backupDir, plan, newManifest: stateManifest });
         applyPlan(rootDir, stagedDir, plan, backupDir);
         // Lockfile written ONLY after a clean apply. The birth stamp is preserved
-        // (agentKitVersion advances; factoryVersion stays frozen).
-        writeLockfile(rootDir, stampBirth(oldLock, manifest));
+        // (agentKitVersion advances; factoryVersion stays frozen). With `--beta`,
+        // `stampBeta` composes `stampBirth` and adds `beta:true`; a stable/plain
+        // update uses `stampBirth` alone, so a prior `beta` is cleared by omission.
+        writeLockfile(rootDir, flags.beta ? stampBeta(oldLock, manifest) : stampBirth(oldLock, manifest));
         clearUpdateState(rootDir);
         maintainDerivedDotfiles(rootDir, stagedDir, manifest.version);
         await maybeCommitBrain(rootDir, manifest.version, [...plan.writes, ...plan.deletes], flags);
@@ -485,6 +541,40 @@ export async function runUpdate(flags, deps = {}) {
         }
     }
 }
+/**
+ * Channel-change guard (finding B3a). A plain/stable `update` over a beta lockfile
+ * is a CHANNEL CHANGE (beta → stable) and must NEVER happen silently:
+ *   - `--beta` / `--stable` explicit → no guard (the flag IS the intent).
+ *   - interactive (TTY) → ask for confirmation; abort if declined.
+ *   - headless (no TTY) → REJECT with a clear message + clean exit. It does NOT
+ *     degrade or auto-proceed (auto-proceeding would reintroduce the very silent
+ *     downgrade this kills); the repo stays on beta. Use `--stable` to opt out.
+ *
+ * `oldLock.beta === false` (explicit) or absent ≡ a stable lockfile → no guard.
+ */
+async function guardChannelChange(oldLock, flags) {
+    if (oldLock.beta !== true)
+        return; // stable lockfile → nothing to guard
+    if (flags.beta || flags.stable)
+        return; // explicit intent → no prompt
+    if (!process.stdout.isTTY) {
+        // Headless: reject, do not degrade. Exit code 0 — this is a refusal to change
+        // channels, not a failure (the brain is untouched, the repo stays on beta).
+        throw new CLIError('Este repo está en el canal beta. Un `update` sin `--beta` cambiaría de canal ' +
+            '(beta → estable) y en modo headless eso se rechaza para no degradar en silencio.\n' +
+            'Usa `factory update --beta` para seguir en beta, o `factory update --stable` para salir al estable.', 0);
+    }
+    const { proceed } = await prompts({
+        type: 'confirm',
+        name: 'proceed',
+        message: 'Este repo está en el canal beta. Un `update` sin `--beta` te saca del canal (beta → estable). ' +
+            '¿Salir del canal beta y bajar al estable?',
+        initial: false,
+    });
+    if (!proceed) {
+        throw new CLIError('Operación cancelada; sigues en el canal beta. Usa `factory update --beta` para actualizar dentro de beta.', 130);
+    }
+}
 /** Warn the dev before a legacy auto-register sync (design §8 edge case). */
 async function confirmLegacy(profile) {
     const detected = profile === PROFILES.full

package/dist/index.js

@@ -27,6 +27,7 @@ Comandos:
   new <Nombre>     Crea un proyecto derivado nuevo (repo + perfil + git init)
   add              Instala el cerebro (.claude/) en el repo actual
   update           Actualiza el cerebro al día sin pisar tu trabajo local
+  beta             Atajo de \`update --beta\`: instala el cerebro del canal beta
   status           Reporta la versión instalada vs. la última disponible
   doctor           Detecta huérfanos, conflictos y rules sin importar + aviso de seguridad
   publish <qué>    Publica el entregable (proposal|mockup|both) a proposals.timekast.mx
@@ -52,6 +53,10 @@ Sobre \`update\`:
     --mine-all     Conserva tu versión en todos los conflictos
     --resume       Retoma un update interrumpido sin re-descargar
     --verify       Reporta diferencias disco-vs-lockfile sin modificar nada
+    --beta         Entra al canal beta (instala el último pre-release \`-beta.N\`)
+    --stable       Sale del canal beta y baja al estable (limpia \`beta\` del lockfile)
+  Un \`update\` sin \`--beta\` sobre un lockfile beta pide confirmación (y en headless
+  rechaza, sin degradar en silencio).
 
 Sobre \`status\` y \`doctor\`:
   Solo diagnostican — nunca modifican archivos. \`status\` lee el lockfile y
@@ -103,6 +108,12 @@ async function main(argv) {
             await runUpdate(parseUpdateFlags(rest));
             return;
         }
+        case 'beta': {
+            // Ad-hoc alias of `update --beta` (NOT injected into derivatives). Forces the
+            // beta channel while still honoring the other update flags the dev may pass.
+            await runUpdate(parseUpdateFlags([...rest, '--beta']));
+            return;
+        }
         case 'status': {
             await runStatus();
             return;

package/dist/lib/lockfile.js

@@ -133,6 +133,9 @@ export function parseLockfile(raw, source = 'lockfile') {
         // Optional birth stamp — present in stamped lockfiles, absent in the
         // builder's embedded manifest and in legacy lockfiles (back-compat).
         ...(typeof obj.factoryVersion === 'string' ? { factoryVersion: obj.factoryVersion } : {}),
+        // Optional beta marker — only a boolean survives; null/string/missing are
+        // dropped (defensive whitelist), so legacy lockfiles stay back-compat.
+        ...(typeof obj.beta === 'boolean' ? { beta: obj.beta } : {}),
     };
 }
 /** Read + validate the lockfile from a derived project root. */

package/dist/lib/package-json.js

@@ -102,9 +102,34 @@ export function kitLocalScripts(rootDir) {
         : {};
 }
 /**
- * Rename `package.json.name` and ensure the `factory:*` scripts (+ the
- * file-gated kit-local `extraScripts`, see `kitLocalScripts`) exist, preserving
- * everything else. Returns the serialized document (with the original
+ * Source dirs that never ship to a derivative — excluded from BOTH dist profiles
+ * (`distribution/`, `cli/`). A boilerplate script that shells one of these (e.g.
+ * `dist:beta` → `tsx distribution/cut-beta.ts`) would be dead noise in a
+ * derivative, which has no such dir. Path-based (not a name list) so a future
+ * origin-only script is stripped by construction, never silently leaked.
+ */
+const ORIGIN_ONLY_SCRIPT_PATHS = ['distribution/', 'cli/'];
+/**
+ * Remove boilerplate scripts that shell an origin-only path (see
+ * `ORIGIN_ONLY_SCRIPT_PATHS`). Mutates `pkg.scripts` in place. Runs ONLY on the
+ * `new` flow (boilerplate seeding from the Factory's own package.json); the
+ * `update`/`add` flows touch a derivative's OWN package.json and never add these.
+ */
+function stripOriginOnlyScripts(pkg) {
+    const scripts = pkg.scripts;
+    if (!scripts)
+        return;
+    for (const [scriptName, cmd] of Object.entries(scripts)) {
+        if (ORIGIN_ONLY_SCRIPT_PATHS.some((p) => cmd.includes(p))) {
+            delete scripts[scriptName];
+        }
+    }
+}
+/**
+ * Rename `package.json.name`, strip origin-only scripts that would be dead in a
+ * derivative (see `stripOriginOnlyScripts`), and ensure the `factory:*` scripts
+ * (+ the file-gated kit-local `extraScripts`, see `kitLocalScripts`) exist,
+ * preserving everything else. Returns the serialized document (with the original
  * indentation + trailing newline).
  *
  * If `factory:update` already exists with a different value it is left intact;
@@ -114,6 +139,7 @@ export function applyPackageJsonEdits(raw, name, extraScripts = {}) {
     const indent = detectIndent(raw);
     const pkg = parsePackageJson(raw);
     pkg.name = name;
+    stripOriginOnlyScripts(pkg);
     const { primary } = ensureFactoryScripts(pkg, extraScripts);
     const content = `${JSON.stringify(pkg, null, indent)}\n`;
     return { content, scriptAlreadyPresent: primary.action === 'conflict' };

package/dist/lib/semver.js

@@ -0,0 +1,76 @@
+/**
+ * Minimal, total semver comparator for the version strings the CLI actually
+ * sees (`X.Y.Z` releases and `X.Y.Z-beta.N` pre-releases). It implements ONLY
+ * the three rules the beta channel needs — NOT a full semver range engine
+ * (no `^`/`~`/`>`/coercion). The CLI keeps ≤3 runtime deps and deliberately
+ * does not pull in the `semver` package for this (DIST BETA-001).
+ *
+ * The three rules (design §11 / B3b):
+ *   1. Numeric core, field by field (`major.minor.patch`). Missing fields → 0.
+ *   2. Same core → a pre-release is LOWER than the bare release
+ *      (`10.9.0-beta.0` < `10.9.0`). This is the heart of B3b: the previous
+ *      naive comparator (`status.ts` `compareVersions`) parsed `0-beta` as `0`
+ *      and treated the pre-release as EQUAL to the release.
+ *   3. Two pre-releases of the same core → compare their numeric suffix N
+ *      (`-beta.1` > `-beta.0`).
+ *
+ * 🔒 TOTAL (never throws). A malformed input (e.g. `"latest"`, `""`, `"x.y"`)
+ * must never crash: non-numeric segments collapse to 0, so the function still
+ * returns a deterministic order. This preserves the existing contract — `status`
+ * guarantees exit 0 and its old comparator was tolerant (`parseInt(...) || 0`).
+ */
+/** Coerce a string segment to a finite integer; anything non-numeric → 0 (total contract). */
+function toInt(segment) {
+    const n = Number.parseInt(segment, 10);
+    return Number.isNaN(n) ? 0 : n;
+}
+/**
+ * Parse a version string into its core + pre-release parts. Tolerant by design:
+ * strips an optional leading `v`, splits on the FIRST `-` into core vs suffix,
+ * and never throws. Any pre-release suffix (`-beta.N`, `-rc.1`, …) marks the
+ * version as a pre-release; only the trailing numeric component is read as N.
+ */
+function parse(version) {
+    const raw = version.startsWith('v') ? version.slice(1) : version;
+    const dashIdx = raw.indexOf('-');
+    const corePart = dashIdx === -1 ? raw : raw.slice(0, dashIdx);
+    const suffix = dashIdx === -1 ? '' : raw.slice(dashIdx + 1);
+    const core = corePart.split('.').map(toInt);
+    const isPrerelease = suffix.length > 0;
+    // N = last dotted component of the suffix (`beta.3` → `3`, `rc.1` → `1`).
+    // A non-numeric tail (`beta.foo`) collapses to 0 (total contract).
+    const suffixParts = suffix.split('.');
+    const prereleaseN = isPrerelease ? toInt(suffixParts[suffixParts.length - 1]) : 0;
+    return { core, isPrerelease, prereleaseN };
+}
+/**
+ * Compare two version strings.
+ *
+ * @returns negative when `a < b`, `0` when equal, positive when `a > b`.
+ *          Never throws; malformed input yields a deterministic order (0 for the
+ *          unparseable segments).
+ *
+ * PARITY: `distribution/cut-beta.ts#compareSemver` is a deliberate copy of these
+ * 3 §11 rules (kept out of a cross-package import). If you change the rules here,
+ * mirror them there and re-run both suites (semver.test.ts + cut-beta.test.ts).
+ */
+export function compare(a, b) {
+    const pa = parse(a);
+    const pb = parse(b);
+    // Rule 1: numeric core, field by field. Missing fields compare as 0.
+    const len = Math.max(pa.core.length, pb.core.length);
+    for (let i = 0; i < len; i++) {
+        const da = pa.core[i] ?? 0;
+        const db = pb.core[i] ?? 0;
+        if (da !== db)
+            return da - db;
+    }
+    // Same core. Rule 2: a pre-release is LOWER than the bare release.
+    if (pa.isPrerelease !== pb.isPrerelease) {
+        // a is the pre-release → a < b → negative; otherwise positive.
+        return pa.isPrerelease ? -1 : 1;
+    }
+    // Rule 3: both pre-release (or both stable) → compare numeric suffix N.
+    // Two stable versions of the same core both have N = 0 → equal (returns 0).
+    return pa.prereleaseN - pb.prereleaseN;
+}

package/dist/lib/unpack.js

@@ -19,6 +19,7 @@ import { execa } from 'execa';
 import { extract } from 'tar';
 import { CLIError } from './cli-error.js';
 import { FACTORY_REPO, MANIFEST_FILE, TIMEKAST_DIR } from './constants.js';
+import { compare } from './semver.js';
 /** Download the profile tarball into `tmpDir`; returns the tarball path. */
 export async function downloadProfileTarball(profile, tmpDir) {
     try {
@@ -44,6 +45,89 @@ export async function downloadProfileTarball(profile, tmpDir) {
     }
     return path.join(tmpDir, downloaded[0]);
 }
+/**
+ * Marker that a tag belongs to the beta channel. The filter matches on this
+ * substring of the `tagName` ONLY — never the release body — so a release whose
+ * notes happen to mention `-beta.` (but whose tag is a stable `vX.Y.Z`) is never
+ * picked up (§8 edge case). Other pre-release channels (`-rc.`, `-test`) carry a
+ * different marker, so they are excluded by construction.
+ */
+const BETA_TAG_MARKER = '-beta.';
+/** No beta release exists in the Factory repo — a defined, user-facing failure. */
+export class BetaNotFoundError extends CLIError {
+    constructor(message, exitCode = 1) {
+        super(message, exitCode);
+        this.name = 'BetaNotFoundError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Pick the latest beta release out of a list of releases.
+ *
+ * Filters to entries whose `tagName` carries the `-beta.` marker, then selects
+ * the highest by **semver-max** (BETA-001's `compare`), NOT by GitHub's
+ * newest-first ordering: `gh release list` sorts by publish date and interleaves
+ * `-rc.`/`-test` tags, and a `-beta.1` can be published before a `-beta.0`. Only
+ * the semver suffix N decides the winner.
+ *
+ * @throws {BetaNotFoundError} when no release carries the `-beta.` marker.
+ */
+export function resolveLatestBeta(releases) {
+    const betas = releases.filter((r) => r.tagName.includes(BETA_TAG_MARKER));
+    if (betas.length === 0) {
+        throw new BetaNotFoundError(`No hay un beta publicado en \`${FACTORY_REPO}\`.\n` +
+            'Verifica que exista un pre-release con tag `-beta.N` antes de usar el canal beta.');
+    }
+    // semver-max: `compare` strips the leading `v` itself, so tags pass verbatim.
+    return betas.reduce((max, r) => (compare(r.tagName, max.tagName) > 0 ? r : max));
+}
+/**
+ * Download the latest beta profile tarball into `tmpDir`; returns the tarball
+ * path. Beta counterpart of {@link downloadProfileTarball}: instead of letting
+ * `gh` resolve "latest" (which excludes pre-releases), it lists the releases,
+ * resolves the highest `-beta.N` by semver, and downloads that release BY TAG.
+ *
+ * A network/`gh` failure surfaces as-is — only an empty beta list (a successful
+ * query that returns no beta) yields {@link BetaNotFoundError}, so a real outage
+ * is never masked as "no beta published" (§8 edge case).
+ */
+export async function downloadBetaProfileTarball(profile, tmpDir) {
+    const { stdout } = await execa('gh', [
+        'release',
+        'list',
+        '--repo',
+        FACTORY_REPO,
+        '--json',
+        'tagName,isPrerelease',
+        '--limit',
+        '30',
+    ]);
+    const releases = JSON.parse(stdout);
+    const latestBeta = resolveLatestBeta(releases);
+    try {
+        await execa('gh', [
+            'release',
+            'download',
+            latestBeta.tagName,
+            '--repo',
+            FACTORY_REPO,
+            '--pattern',
+            `tk-${profile}-*.tgz`,
+            '--dir',
+            tmpDir,
+        ]);
+    }
+    catch {
+        throw new CLIError(`No se pudo descargar el asset \`${profile}\` del beta \`${latestBeta.tagName}\` en \`${FACTORY_REPO}\`.\n` +
+            'Verifica que el pre-release contenga los assets de distribución.');
+    }
+    const downloaded = readdirSync(tmpDir).filter((f) => f.endsWith('.tgz'));
+    if (downloaded.length === 0) {
+        throw new CLIError(`El beta \`${latestBeta.tagName}\` no contiene un asset para el perfil \`${profile}\`. ` +
+            'Verifica el pre-release del Factory.');
+    }
+    return path.join(tmpDir, downloaded[0]);
+}
 /**
  * Extract `tarball` into a fresh staging dir under `tmpDir` and validate that it
  * carries an embedded `.timekast/manifest.json`. Returns the staging dir + the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timekast/factory",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Public, thin CLI to bootstrap and maintain TimeKast Factory derived projects.",
   "type": "module",
   "license": "UNLICENSED",