@timekast/factory 1.1.0 → 1.2.0

package/dist/commands/publish.js

@@ -0,0 +1,181 @@
+/**
+ * `factory publish <proposal|mockup|both>` — publish a derived project's static
+ * deliverable(s) to the `TimeKast/proposals` hub (plan v4.1).
+ *
+ * Security model is honest: link-no-adivinable + noindex only (no password yet).
+ * Identity = repo name (unique in the org) + unguessable token; both sticky in
+ * `project/.publish.json`. The CLI pushes to the hub but NEVER commits the derived
+ * repo — that's the workflow's job (the `--commit` opt-in is for standalone use).
+ *
+ * Expected failures throw `CLIError`; the top-level handler prints + exits.
+ */
+import { mkdtempSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { execa } from 'execa';
+import { CLIError } from '../lib/cli-error.js';
+import { PROPOSALS_HUB_REPO } from '../lib/constants.js';
+import { buildUrl, DELIVERABLE_DIR, deliverableExists, findExistingToken, findHtmlEntry, generateToken, hasNoindexMeta, parseRepoSlug, proposalFolder, readPublishState, slugify, writePublishState, } from '../lib/publish-core.js';
+import { cloneHubShallow, commitAndPush, copyDeliverable, gitRemoteUrl, listHubFolders, resolveAuthToken, } from '../lib/publish-engine.js';
+import { detectRepo } from '../lib/repo-detection.js';
+/** Parse `publish`'s argv: a mandatory `<proposal|mockup|both>` + flags. */
+export function parsePublishArgs(argv) {
+    const positional = argv.find((a) => !a.startsWith('-'));
+    if (!positional) {
+        throw new CLIError('Falta el argumento. Uso: `factory publish <proposal|mockup|both>` ' +
+            '(explícito a propósito — no se publica "lo que haya").');
+    }
+    let targets;
+    if (positional === 'both')
+        targets = ['proposal', 'mockup'];
+    else if (positional === 'proposal' || positional === 'mockup')
+        targets = [positional];
+    else {
+        throw new CLIError(`Argumento inválido: \`${positional}\`. Usa \`proposal\`, \`mockup\` o \`both\`.`);
+    }
+    return {
+        targets,
+        flags: {
+            opaqueUrl: argv.includes('--opaque-url'),
+            changeUrl: argv.includes('--change-url'),
+            commit: argv.includes('--commit'),
+        },
+    };
+}
+export async function runPublish(parsed) {
+    const cwd = process.cwd();
+    const { hasRepo, repoRoot } = detectRepo(cwd);
+    if (!hasRepo) {
+        throw new CLIError('No hay repositorio git aquí. `factory publish` corre dentro de un derivado.');
+    }
+    const root = repoRoot ?? cwd;
+    // Only publish requested deliverables that actually exist.
+    const present = parsed.targets.filter((t) => deliverableExists(root, t));
+    if (present.length === 0) {
+        throw new CLIError(`No encontré ${parsed.targets.join('/')} en este repo. ` +
+            'Corre `/proposal` o `/mockup` primero para generar el entregable.');
+    }
+    // Auth (dual): env token (headless) or gh + org membership (dev local).
+    const token = await resolveAuthToken();
+    // Identity: repo name from the git remote (unique in the org). Fallback to dir.
+    const remoteUrl = await gitRemoteUrl(root);
+    const repo = (remoteUrl && parseRepoSlug(remoteUrl)) || slugify(path.basename(root));
+    if (!remoteUrl) {
+        console.warn(`Aviso: este repo no tiene remote \`origin\`; uso el nombre del directorio (\`${repo}\`) como identidad.`);
+    }
+    const existing = readPublishState(root);
+    // Shallow-clone the hub into an ephemeral tmpdir.
+    const tmp = mkdtempSync(path.join(tmpdir(), 'tk-publish-'));
+    const cleanup = () => {
+        try {
+            rmSync(tmp, { recursive: true, force: true });
+        }
+        catch {
+            /* best effort */
+        }
+    };
+    const onSignal = () => {
+        cleanup();
+        process.exit(130);
+    };
+    process.once('SIGINT', onSignal);
+    process.once('SIGTERM', onSignal);
+    try {
+        const hubDir = path.join(tmp, 'hub');
+        await cloneHubShallow(token, hubDir);
+        // Resolve token + urlShape (sticky in .publish.json; hub-query as fallback).
+        const { proposalToken, urlShape } = resolveTokenAndShape(existing, parsed.flags, repo, hubDir);
+        const folder = proposalFolder(repo, proposalToken, urlShape);
+        const urls = { ...(existing?.urls ?? {}) };
+        const publishedFolders = new Set();
+        for (const type of present) {
+            const srcDir = path.join(root, DELIVERABLE_DIR[type]);
+            const files = readdirSync(srcDir);
+            const htmlEntry = findHtmlEntry(files);
+            if (!htmlEntry) {
+                throw new CLIError(`No encontré un HTML en \`${DELIVERABLE_DIR[type]}\`. ¿Se generó el entregable?`);
+            }
+            const indexPath = copyDeliverable(srcDir, hubDir, folder, type, htmlEntry);
+            // Verify (not inject) the noindex meta — the template owns the HTML.
+            const html = readFileSync(indexPath, 'utf8');
+            if (!hasNoindexMeta(html)) {
+                throw new CLIError(`El entregable \`${type}\` no trae \`<meta name="robots" content="noindex,nofollow">\`. ` +
+                    'El template debe emitirlo; no se publica sin él (no lo inyecto).');
+            }
+            urls[type] = buildUrl(folder, type);
+            publishedFolders.add(folder);
+        }
+        await commitAndPush(hubDir, `publish: ${repo} (${present.join(', ')})`, [...publishedFolders]);
+        // Persist sticky state in the derived repo working tree (NO commit here).
+        writePublishState(root, {
+            repo,
+            token: proposalToken,
+            urlShape,
+            urls,
+            publishedAt: new Date().toISOString(),
+        });
+        if (parsed.flags.commit) {
+            await commitDerivedRepo(root, present, repo);
+        }
+        reportSuccess(present, urls, parsed.flags.commit);
+    }
+    finally {
+        process.removeListener('SIGINT', onSignal);
+        process.removeListener('SIGTERM', onSignal);
+        cleanup();
+    }
+}
+/** Resolve the sticky token + urlShape, honoring `.publish.json` then the hub. */
+function resolveTokenAndShape(existing, flags, repo, hubDir) {
+    if (existing) {
+        const wantsOpaque = flags.opaqueUrl;
+        const isOpaque = existing.urlShape === 'opaque';
+        if (wantsOpaque !== isOpaque && !flags.changeUrl) {
+            throw new CLIError(`Esta propuesta ya se publicó como \`${existing.urlShape}\`. Cambiar la forma de URL ` +
+                'rompería el link que el cliente ya tiene. Si es a propósito, pasa `--change-url` ' +
+                '(la ruta vieja queda huérfana — bájala con `factory unpublish`).');
+        }
+        const urlShape = flags.changeUrl
+            ? flags.opaqueUrl
+                ? 'opaque'
+                : 'named'
+            : existing.urlShape;
+        if (flags.changeUrl && urlShape !== existing.urlShape) {
+            console.warn('Aviso: cambiaste la forma de URL. La ruta anterior queda huérfana en el hub ' +
+                '(bájala con `factory unpublish` si ya no la quieres).');
+        }
+        return { proposalToken: existing.token, urlShape };
+    }
+    // First publish: named → reuse a hub folder if one exists (uniqueness = ownership).
+    const urlShape = flags.opaqueUrl ? 'opaque' : 'named';
+    if (urlShape === 'named') {
+        const hit = findExistingToken(repo, listHubFolders(hubDir));
+        if (hit && 'ambiguous' in hit) {
+            throw new CLIError(`Hay más de una carpeta \`${repo}-*\` en el hub y no hay \`.publish.json\` local para desambiguar. ` +
+                'No adivino cuál es tuya — resuélvelo a mano en el hub o restaura tu `.publish.json`.');
+        }
+        if (hit)
+            return { proposalToken: hit.token, urlShape };
+    }
+    return { proposalToken: generateToken(), urlShape };
+}
+/** `--commit` opt-in: commit the deliverable + state in the derived repo (pathspec-scoped). */
+async function commitDerivedRepo(root, types, repo) {
+    const paths = [...types.map((t) => DELIVERABLE_DIR[t]), path.join('project', '.publish.json')];
+    await execa('git', ['add', '--', ...paths], { cwd: root, reject: false });
+    const res = await execa('git', ['commit', '-m', `chore: publish ${repo} → ${PROPOSALS_HUB_REPO}`, '--', ...paths], { cwd: root, reject: false });
+    if (res.exitCode === 0) {
+        console.log('• Commit del entregable + .publish.json hecho en el repo derivado (--commit).');
+    }
+}
+function reportSuccess(types, urls, committed) {
+    console.log(`\n✔ Publicado en ${PROPOSALS_HUB_REPO} (Vercel redeploya solo).`);
+    for (const t of types) {
+        if (urls[t])
+            console.log(`  ${t}: ${urls[t]}`);
+    }
+    if (!committed) {
+        console.log('\nℹ El entregable + `project/.publish.json` quedaron escritos pero SIN commitear. ' +
+            'El workflow los commitea al cerrar; en uso suelto, commitéalos tú (o usa `--commit`).');
+    }
+}

package/dist/commands/unpublish.js

@@ -0,0 +1,81 @@
+/**
+ * `factory unpublish [proposal|mockup|both]` — take a published deliverable down
+ * from the hub (plan v4.1). The recourse against a leaked link in the static,
+ * password-less model: it mata el link (cuts future access via the hub), but is
+ * contención, NOT recall — anything already fetched by an unfurler lives in third
+ * party caches outside our control.
+ *
+ * Same machinery as publish (auth → shallow clone → mutate → rebase-retry push);
+ * no new infra. Keeps the token sticky in `.publish.json` so a later re-publish
+ * reuses the same URL.
+ */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { CLIError } from '../lib/cli-error.js';
+import { PROPOSALS_HUB_REPO } from '../lib/constants.js';
+import { proposalFolder, readPublishState, writePublishState, } from '../lib/publish-core.js';
+import { cloneHubShallow, commitAndPush, removeDeliverable, resolveAuthToken, } from '../lib/publish-engine.js';
+import { detectRepo } from '../lib/repo-detection.js';
+/** Parse the optional `<proposal|mockup|both>` arg (default: both). */
+export function parseUnpublishTargets(argv) {
+    const positional = argv.find((a) => !a.startsWith('-'));
+    if (!positional || positional === 'both')
+        return ['proposal', 'mockup'];
+    if (positional === 'proposal' || positional === 'mockup')
+        return [positional];
+    throw new CLIError(`Argumento inválido: \`${positional}\`. Usa \`proposal\`, \`mockup\` o \`both\`.`);
+}
+export async function runUnpublish(targets) {
+    const cwd = process.cwd();
+    const { hasRepo, repoRoot } = detectRepo(cwd);
+    if (!hasRepo) {
+        throw new CLIError('No hay repositorio git aquí. `factory unpublish` corre dentro de un derivado.');
+    }
+    const root = repoRoot ?? cwd;
+    const state = readPublishState(root);
+    if (!state) {
+        throw new CLIError('No hay `project/.publish.json` en este repo — no sé qué bajar. ' +
+            'Esta propuesta no fue publicada desde aquí (o el estado se perdió).');
+    }
+    const token = await resolveAuthToken();
+    const folder = proposalFolder(state.repo, state.token, state.urlShape);
+    const tmp = mkdtempSync(path.join(tmpdir(), 'tk-unpublish-'));
+    const cleanup = () => {
+        try {
+            rmSync(tmp, { recursive: true, force: true });
+        }
+        catch {
+            /* best effort */
+        }
+    };
+    process.once('SIGINT', cleanup);
+    process.once('SIGTERM', cleanup);
+    try {
+        const hubDir = path.join(tmp, 'hub');
+        await cloneHubShallow(token, hubDir);
+        const removed = [];
+        for (const type of targets) {
+            if (removeDeliverable(hubDir, folder, type))
+                removed.push(type);
+        }
+        if (removed.length === 0) {
+            console.log('No había nada que bajar en el hub para esta propuesta. Nada que hacer.');
+            return;
+        }
+        await commitAndPush(hubDir, `unpublish: ${state.repo} (${removed.join(', ')})`, [folder]);
+        // Drop the removed URLs from the sticky state (keep the token for re-publish).
+        const urls = { ...state.urls };
+        for (const type of removed)
+            delete urls[type];
+        writePublishState(root, { ...state, urls, publishedAt: new Date().toISOString() });
+        console.log(`\n✔ Bajado de ${PROPOSALS_HUB_REPO}: ${removed.join(', ')}.`);
+        console.log('ℹ Esto corta el acceso futuro vía el hub, pero NO recupera lo ya filtrado ' +
+            '(un link reenviado pudo quedar cacheado por terceros).');
+    }
+    finally {
+        process.removeListener('SIGINT', cleanup);
+        process.removeListener('SIGTERM', cleanup);
+        cleanup();
+    }
+}

package/dist/index.js

@@ -13,7 +13,9 @@ import { CLIError } from './lib/cli-error.js';
 import { parseAddFlags, runAdd } from './commands/add.js';
 import { runDoctor } from './commands/doctor.js';
 import { runNew } from './commands/new.js';
+import { parsePublishArgs, runPublish } from './commands/publish.js';
 import { runStatus } from './commands/status.js';
+import { parseUnpublishTargets, runUnpublish } from './commands/unpublish.js';
 import { parseUpdateFlags, runUpdate } from './commands/update.js';
 const HELP = `
 @timekast/factory — bootstrap y mantenimiento de proyectos derivados del Factory.
@@ -27,6 +29,8 @@ Comandos:
   update           Actualiza el cerebro al día sin pisar tu trabajo local
   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
+  unpublish [qué]  Baja del hub un entregable publicado (proposal|mockup|both; default both)
 
 Sobre \`add\`:
   Requiere estar dentro de un repo git (al menos \`git init\`). Por default instala
@@ -107,6 +111,14 @@ async function main(argv) {
             runDoctor();
             return;
         }
+        case 'publish': {
+            await runPublish(parsePublishArgs(rest));
+            return;
+        }
+        case 'unpublish': {
+            await runUnpublish(parseUnpublishTargets(rest));
+            return;
+        }
         default:
             throw new CLIError(`Comando desconocido: \`${command}\`.\nEjecuta \`factory --help\` para ver los comandos disponibles.`);
     }

package/dist/lib/constants.js

@@ -7,6 +7,10 @@
 export const FACTORY_ORG = 'TimeKast';
 /** The Factory monorepo, source of the distribution releases. */
 export const FACTORY_REPO = 'TimeKast/TimeKast-Factory';
+/** The static hub repo that hosts published proposals/mockups (`factory publish`). */
+export const PROPOSALS_HUB_REPO = `${FACTORY_ORG}/proposals`;
+/** HTTPS git URL of the hub (token is injected by the publish command). */
+export const PROPOSALS_HUB_GIT = `https://github.com/${FACTORY_ORG}/proposals.git`;
 /** Distribution profiles selectable in `new`. */
 export const PROFILES = {
     full: 'full',
@@ -36,6 +40,10 @@ export const DOCTOR_SCRIPT_NAME = 'factory:doctor';
 export const DOCTOR_SCRIPT_CMD = 'npx @timekast/factory doctor';
 export const STATUS_SCRIPT_NAME = 'factory:status';
 export const STATUS_SCRIPT_CMD = 'npx @timekast/factory status';
+export const PUBLISH_SCRIPT_NAME = 'factory:publish';
+export const PUBLISH_SCRIPT_CMD = 'npx @timekast/factory publish';
+export const UNPUBLISH_SCRIPT_NAME = 'factory:unpublish';
+export const UNPUBLISH_SCRIPT_CMD = 'npx @timekast/factory unpublish';
 /**
  * All convenience scripts the installer ensures in a Node derivative's
  * package.json (each: add if missing, never overwrite a divergent value). Keyed
@@ -46,4 +54,6 @@ export const FACTORY_SCRIPTS = {
     [UPDATE_SCRIPT_NAME]: UPDATE_SCRIPT_CMD,
     [DOCTOR_SCRIPT_NAME]: DOCTOR_SCRIPT_CMD,
     [STATUS_SCRIPT_NAME]: STATUS_SCRIPT_CMD,
+    [PUBLISH_SCRIPT_NAME]: PUBLISH_SCRIPT_CMD,
+    [UNPUBLISH_SCRIPT_NAME]: UNPUBLISH_SCRIPT_CMD,
 };

package/dist/lib/publish-core.js

@@ -0,0 +1,122 @@
+/**
+ * Pure helpers for `factory publish` / `factory unpublish` (kept side-effect-free
+ * where possible so they unit-test without mocks). The git/gh/network seams live
+ * in the commands; everything here is deterministic given its inputs.
+ *
+ * Identity model (plan v4.1): a proposal's hub folder is `{repo}-{token}` where
+ * `repo` is the derived project's repo name (unique within the org → ownership is
+ * free) and `token` is an unguessable suffix. `--opaque-url` drops the repo name
+ * (`p-{token}`) for clients whose name must not travel in the link.
+ */
+import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+/** Source dir (relative to repo root) for each deliverable. */
+export const DELIVERABLE_DIR = {
+    proposal: path.join('project', 'presentation'),
+    mockup: path.join('project', 'mockup'),
+};
+/** The public domain the hub serves under. */
+export const PROPOSALS_DOMAIN = 'proposals.timekast.mx';
+/** Relative path (from repo root) to the persisted publish state. */
+export const PUBLISH_STATE_FILE = path.join('project', '.publish.json');
+const TOKEN_ALPHABET = 'abcdefghijklmnopqrstuvwxyz0123456789'; // base36 — URL-safe, case-insensitive
+const TOKEN_LENGTH = 16;
+/**
+ * Generate an unguessable token (16 base36 chars ≈ 82 bits). Not a secret in the
+ * access-control sense — it makes the URL non-guessable and prevents enumeration.
+ */
+export function generateToken() {
+    const bytes = randomBytes(TOKEN_LENGTH);
+    let out = '';
+    for (let i = 0; i < TOKEN_LENGTH; i++) {
+        out += TOKEN_ALPHABET[bytes[i] % TOKEN_ALPHABET.length];
+    }
+    return out;
+}
+/**
+ * Parse the repo name from a git remote URL (ssh or https forms), e.g.
+ * `git@github.com:TimeKast/fimubac.git` / `https://github.com/TimeKast/fimubac` → `fimubac`.
+ * Returns null when the URL has no recognizable `…/repo` tail.
+ */
+export function parseRepoSlug(remoteUrl) {
+    const trimmed = remoteUrl.trim().replace(/\.git$/, '');
+    // Last path segment after `/` or `:` (ssh scp-like form uses `:`).
+    const match = trimmed.match(/[/:]([^/:]+)$/);
+    const name = match?.[1];
+    if (!name)
+        return null;
+    const slug = slugify(name);
+    return slug || null;
+}
+/** Lowercase + collapse non-alphanumerics to single dashes; trim dashes. */
+export function slugify(input) {
+    return input
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/** The hub folder name for a proposal, given its identity + URL shape. */
+export function proposalFolder(repo, token, shape) {
+    return shape === 'opaque' ? `p-${token}` : `${repo}-${token}`;
+}
+/** The public URL for a published deliverable (trailing slash → relative assets resolve). */
+export function buildUrl(folder, type) {
+    return `https://${PROPOSALS_DOMAIN}/${folder}/${type}/`;
+}
+/** True when the HTML carries a `<meta name="robots" … noindex …>` (order-tolerant). */
+export function hasNoindexMeta(html) {
+    const nameThenContent = /<meta[^>]+name=["']robots["'][^>]*content=["'][^"']*noindex[^"']*["']/i;
+    const contentThenName = /<meta[^>]+content=["'][^"']*noindex[^"']*["'][^>]*name=["']robots["']/i;
+    return nameThenContent.test(html) || contentThenName.test(html);
+}
+/** True when the deliverable's source dir exists in the derived repo. */
+export function deliverableExists(root, type) {
+    return existsSync(path.join(root, DELIVERABLE_DIR[type]));
+}
+/**
+ * Resolve the HTML entry filename inside a deliverable source dir. Mockups ship
+ * `index.html`; proposals ship `{slug}-proposal.html`. Returns the filename to
+ * rename to `index.html` in the hub, or null when no HTML entry is found.
+ */
+export function findHtmlEntry(files) {
+    if (files.includes('index.html'))
+        return 'index.html';
+    const proposal = files.find((f) => /-proposal\.html$/.test(f));
+    if (proposal)
+        return proposal;
+    const anyHtml = files.find((f) => f.endsWith('.html'));
+    return anyHtml ?? null;
+}
+/** Read the persisted publish state, or null when absent / unparseable. */
+export function readPublishState(root) {
+    const file = path.join(root, PUBLISH_STATE_FILE);
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Write the persisted publish state (pretty-printed, trailing newline). */
+export function writePublishState(root, state) {
+    const file = path.join(root, PUBLISH_STATE_FILE);
+    writeFileSync(file, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+/**
+ * Find an existing folder for `repo` among the hub's top-level entries (named
+ * shape only — opaque folders carry no repo name, so they rely on local state).
+ * Because the repo name is unique in the org, any `{repo}-*` match is ours.
+ * Returns the token, or null when none / ambiguous (>1 → caller confirms).
+ */
+export function findExistingToken(repo, hubEntries) {
+    const prefix = `${repo}-`;
+    const matches = hubEntries.filter((e) => e.startsWith(prefix));
+    if (matches.length === 0)
+        return null;
+    if (matches.length > 1)
+        return { ambiguous: true };
+    return { token: matches[0].slice(prefix.length) };
+}

package/dist/lib/publish-engine.js

@@ -0,0 +1,133 @@
+/**
+ * I/O seams for `factory publish` / `factory unpublish`: git + gh + filesystem.
+ * Kept apart from the pure helpers (`publish-core.ts`) and the orchestration
+ * (`commands/*.ts`) so the concurrency-sensitive bits (auth, shallow clone,
+ * rebase-retry push) test against an injectable git runner.
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { execa } from 'execa';
+import { CLIError } from './cli-error.js';
+import { FACTORY_ORG } from './constants.js';
+import { runPreflight } from './preflight.js';
+/** Default git runner (never throws on non-zero — callers inspect `exitCode`). */
+export const realGit = async (args, opts) => {
+    const res = await execa('git', args, { cwd: opts?.cwd, reject: false });
+    return { stdout: res.stdout ?? '', exitCode: res.exitCode ?? 1 };
+};
+/**
+ * Resolve a token with push access to the hub. Dual auth (plan B-1):
+ *   - `TIMEKAST_PUBLISH_TOKEN` in env → headless (Agent Server, infra TimeKast).
+ *   - else → dev local: full preflight (gh + org member) then `gh auth token`.
+ * Never reads a token from a derived repo.
+ */
+export async function resolveAuthToken() {
+    const envToken = process.env.TIMEKAST_PUBLISH_TOKEN?.trim();
+    if (envToken)
+        return envToken;
+    await runPreflight();
+    const res = await execa('gh', ['auth', 'token'], { reject: false });
+    const token = (res.stdout ?? '').trim();
+    if (res.exitCode !== 0 || !token) {
+        throw new CLIError('No se pudo obtener un token de GitHub con `gh auth token`. Verifica `gh auth status`.');
+    }
+    return token;
+}
+/** The hub clone URL with an embedded token (lives only in the ephemeral tmpdir). */
+function hubCloneUrl(token) {
+    return `https://x-access-token:${token}@github.com/${FACTORY_ORG}/proposals.git`;
+}
+/** Shallow-clone the hub into `destDir` (no history, no other proposals' assets). */
+export async function cloneHubShallow(token, destDir) {
+    const res = await execa('git', ['clone', '--depth', '1', hubCloneUrl(token), destDir], {
+        reject: false,
+    });
+    if (res.exitCode !== 0) {
+        throw new CLIError(`No se pudo clonar el hub \`${FACTORY_ORG}/proposals\`. ` +
+            'Verifica que el repo exista y que tengas acceso de escritura.\n' +
+            (res.stderr ?? ''));
+    }
+}
+/** List the hub's top-level proposal folders (excludes files + `.git`). */
+export function listHubFolders(cloneDir) {
+    return readdirSync(cloneDir)
+        .filter((e) => e !== '.git')
+        .filter((e) => {
+        try {
+            return statSync(path.join(cloneDir, e)).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/**
+ * Copy a deliverable source dir into the hub clone at `{folder}/{type}`, replacing
+ * any prior content (kills orphans), and rename the HTML entry to `index.html`.
+ * Returns the absolute path of the copied `index.html`.
+ */
+export function copyDeliverable(srcDir, cloneDir, folder, type, htmlEntry) {
+    const destDir = path.join(cloneDir, folder, type);
+    rmSync(destDir, { recursive: true, force: true });
+    mkdirSync(destDir, { recursive: true });
+    cpSync(srcDir, destDir, { recursive: true });
+    const indexPath = path.join(destDir, 'index.html');
+    if (htmlEntry !== 'index.html') {
+        renameSync(path.join(destDir, htmlEntry), indexPath);
+    }
+    return indexPath;
+}
+/** Remove a deliverable folder/type from the hub clone (for `unpublish`). */
+export function removeDeliverable(cloneDir, folder, type) {
+    const target = path.join(cloneDir, folder, type);
+    if (!existsSync(target))
+        return false;
+    rmSync(target, { recursive: true, force: true });
+    // Prune the now-empty parent folder if no sibling deliverable remains.
+    const parent = path.join(cloneDir, folder);
+    try {
+        if (readdirSync(parent).length === 0)
+            rmSync(parent, { recursive: true, force: true });
+    }
+    catch {
+        /* best effort */
+    }
+    return true;
+}
+const MAX_PUSH_ATTEMPTS = 3;
+/**
+ * Stage the given paths, commit, and push — with bounded rebase-retry to survive
+ * concurrent publishes (a second push racing the first gets `non-fast-forward`;
+ * we `pull --rebase` and retry). Uses an explicit pathspec on `add` so a dev's
+ * unrelated staged work is never swept in. No-op when nothing changed.
+ */
+export async function commitAndPush(cloneDir, message, paths, git = realGit) {
+    await git(['add', '--', ...paths], { cwd: cloneDir });
+    const status = await git(['status', '--porcelain'], { cwd: cloneDir });
+    if (!status.stdout.trim())
+        return; // nothing to publish — content identical
+    const commit = await git(['commit', '-m', message], { cwd: cloneDir });
+    if (commit.exitCode !== 0) {
+        throw new CLIError(`No se pudo crear el commit en el hub.\n${commit.stdout}`);
+    }
+    for (let attempt = 1; attempt <= MAX_PUSH_ATTEMPTS; attempt++) {
+        const push = await git(['push'], { cwd: cloneDir });
+        if (push.exitCode === 0)
+            return;
+        if (attempt === MAX_PUSH_ATTEMPTS)
+            break;
+        const rebase = await git(['pull', '--rebase'], { cwd: cloneDir });
+        if (rebase.exitCode !== 0) {
+            throw new CLIError('No se pudo rebasar sobre el hub remoto (conflicto inesperado). ' +
+                'Reintenta `factory publish`; si persiste, revisa el repo del hub.');
+        }
+    }
+    throw new CLIError(`No se pudo pushear al hub tras ${MAX_PUSH_ATTEMPTS} intentos (mucha concurrencia). Reintenta.`);
+}
+/** Resolve the `origin` remote URL of a repo, or null when there is no remote. */
+export async function gitRemoteUrl(root) {
+    const res = await execa('git', ['remote', 'get-url', 'origin'], { cwd: root, reject: false });
+    if (res.exitCode !== 0)
+        return null;
+    return res.stdout.trim() || null;
+}

package/package.json

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