@timekast/factory 1.1.0 → 1.3.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/commands/update.js

@@ -40,7 +40,8 @@ import prompts from 'prompts';
 import { applyPlan, clearUpdateState, defaultBackupDir, hasUpdateState, readUpdateState, validateStagedManifest, writeUpdateState, } from '../lib/atomic-swap.js';
 import { collectClaudePaths } from '../lib/claude-paths.js';
 import { CLIError } from '../lib/cli-error.js';
-import { CLAUDE_MD_FILE, PROFILES } from '../lib/constants.js';
+import { CLAUDE_MD_FILE, GITATTRIBUTES_FILE, PROFILES, } from '../lib/constants.js';
+import { extractManagedBlock, syncManagedBlock } from '../lib/gitattributes.js';
 import { diffLockfiles, hasLockfile, normalizeThenHash, planAutoRegister, readLockfile, writeLockfile, } from '../lib/lockfile.js';
 import { detectProfile, insertFactoryUpdateScript, setAgentKitVersion, } from '../lib/package-json.js';
 import { runPreflight } from '../lib/preflight.js';
@@ -168,9 +169,8 @@ function runResume(rootDir) {
     applyPlan(rootDir, state.stagedDir, state.plan, state.backupDir);
     writeLockfile(rootDir, newLock);
     clearUpdateState(rootDir);
-    const pkgPath = path.join(rootDir, 'package.json');
-    if (existsSync(pkgPath))
-        maintainDerivedPkg(pkgPath, newLock.version);
+    // Maintain dotfiles BEFORE removing the staged dir (the .gitattributes source).
+    maintainDerivedDotfiles(rootDir, state.stagedDir, newLock.version);
     rmSync(state.stagedDir, { recursive: true, force: true });
     console.log('✔ `update` retomado y completado.');
 }
@@ -191,15 +191,31 @@ function warnOnScriptConflict(action, _pkgPath) {
     }
 }
 /**
- * After a sync, maintain the derived project's package.json: ensure the
- * `factory:update` script (warn on a divergent value) and set `agentKitVersion`
- * to the just-installed brain version, mirroring the lockfile's `version`. Run on
- * every update, so the field tracks each `factory:update` (and a derivative whose
- * field was missing or stale gets reconciled — same shape as the Factory's own
+ * After a sync, maintain the derived project's co-owned dotfiles — `package.json`
+ * AND `.gitattributes` — in one place. Centralized (not scattered per command) so
+ * all THREE update paths (main, legacy auto-register, resume) are covered by
+ * construction: a per-command call already regressed once (legacy + resume were
+ * missed). `stagedDir` is the freshly-unpacked tarball, the source of the
+ * `.gitattributes` managed block.
+ */
+function maintainDerivedDotfiles(rootDir, stagedDir, agentKitVersion) {
+    maintainDerivedPkg(rootDir, agentKitVersion);
+    syncDerivedGitattributes(rootDir, stagedDir);
+}
+/**
+ * Maintain the derived project's package.json: ensure the `factory:*` scripts
+ * (warn on a divergent `factory:update`) and set `agentKitVersion` to the
+ * just-installed brain version, mirroring the lockfile's `version`. Run on every
+ * update, so the field tracks each `factory:update` (and a derivative whose field
+ * was missing or stale gets reconciled — same shape as the Factory's own
  * package.json). `factoryVersion` (the frozen birth stamp) and `version` (the app
- * semver) are untouched.
+ * semver) are untouched. No-op (not an error) when the repo has no package.json
+ * (a non-Node derivative).
  */
-function maintainDerivedPkg(pkgPath, agentKitVersion) {
+function maintainDerivedPkg(rootDir, agentKitVersion) {
+    const pkgPath = path.join(rootDir, 'package.json');
+    if (!existsSync(pkgPath))
+        return;
     // Tolerant (mirrors `add`): a malformed package.json must NOT throw AFTER the
     // brain was already applied + the lockfile written — the install succeeded; the
     // script/version mirror is best-effort. Warn and move on.
@@ -212,6 +228,35 @@ function maintainDerivedPkg(pkgPath, agentKitVersion) {
             'Corrige package.json y vuelve a correr `factory update` para sincronizar agentKitVersion.');
     }
 }
+/**
+ * Sync the Factory's managed `.gitattributes` block (the EOL/binary rules that
+ * keep the kit's committed binaries from being corrupted by CRLF→LF normalization)
+ * into the derived repo, preserving the dev's own rules. The canonical block is
+ * READ from the staged tarball (single SSOT), so the rules are never duplicated in
+ * the CLI. Runs even without package.json (a non-Node derivative needs the rules
+ * too). Best-effort like the package.json mirror: a tarball that predates the
+ * managed block (no markers → no block) is a silent no-op, and a write failure
+ * never fails an already-applied update.
+ */
+function syncDerivedGitattributes(rootDir, stagedDir) {
+    try {
+        const srcPath = path.join(stagedDir, GITATTRIBUTES_FILE);
+        if (!existsSync(srcPath))
+            return;
+        const block = extractManagedBlock(readFileSync(srcPath, 'utf8'));
+        if (!block)
+            return;
+        const { action } = syncManagedBlock(rootDir, block);
+        if (action === 'unchanged')
+            return;
+        console.log(action === 'created'
+            ? '✔ `.gitattributes` creado con las reglas de normalización del kit.'
+            : '✔ `.gitattributes`: bloque de reglas del kit sincronizado.');
+    }
+    catch {
+        console.warn('Aviso: no se pudo sincronizar `.gitattributes`; el cerebro se instaló igual.');
+    }
+}
 /** Print the deletes + kept-retired (design §7.6 — visible) + a one-line summary. */
 function reportSummary(diff, manifest) {
     if (diff.deleteSilent.length > 0) {
@@ -335,9 +380,7 @@ export async function runUpdate(flags, deps = {}) {
         // (agentKitVersion advances; factoryVersion stays frozen).
         writeLockfile(rootDir, stampBirth(oldLock, manifest));
         clearUpdateState(rootDir);
-        const pkgPath = path.join(rootDir, 'package.json');
-        if (existsSync(pkgPath))
-            maintainDerivedPkg(pkgPath, manifest.version);
+        maintainDerivedDotfiles(rootDir, stagedDir, manifest.version);
         reportSummary(diff, manifest);
     }
     finally {
@@ -394,9 +437,7 @@ async function applyLegacy(rootDir, stagedDir, manifest) {
     // the just-installed files) PLUS the birth stamp. A legacy auto-register is the
     // first sync this repo records, so the birth seal = the manifest's version.
     writeLockfile(rootDir, { ...manifest, factoryVersion: manifest.version });
-    const pkgPath = path.join(rootDir, 'package.json');
-    if (existsSync(pkgPath))
-        maintainDerivedPkg(pkgPath, manifest.version);
+    maintainDerivedDotfiles(rootDir, stagedDir, manifest.version);
     if (claudeMdExists) {
         console.log('\nConservé tu `CLAUDE.md` (no se sobrescribió). Verifica que importe las rules del kit ' +
             '(`@.claude/rules/*`); corre `factory doctor` para detectar rules sin importar.');

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',
@@ -26,6 +30,23 @@ export const LOCKFILE_FILE = 'lockfile.json';
  * exists on disk (path-match path). See `diffLockfiles` + the install commands.
  */
 export const CLAUDE_MD_FILE = 'CLAUDE.md';
+/**
+ * Repo-root `.gitattributes`. NOT a tracked manifest file (absent from `track`),
+ * so it never flows through the diff/lockfile engine — a derived repo's own rules
+ * would otherwise read as "locally edited" and conflict on every update. Instead a
+ * delimited managed block (markers below) is synced surgically post-apply, like
+ * `package.json` scripts: the block is replaced verbatim, everything outside it is
+ * preserved byte-for-byte. See `syncManagedBlock` in `lib/gitattributes.ts`.
+ */
+export const GITATTRIBUTES_FILE = '.gitattributes';
+/**
+ * Managed-block sentinels. These are PREFIXES (the live source lines carry extra
+ * descriptive text + trailing `>>>`/`<<<`), matched with `startsWith` so detection
+ * survives edits to the comment copy. Do not change without a migration: a derived
+ * repo's existing block is located by these prefixes.
+ */
+export const MANAGED_BLOCK_START = '# >>> timekast-factory managed';
+export const MANAGED_BLOCK_END = '# <<< timekast-factory managed';
 /** The scripts the CLI injects into a derived project's package.json. */
 export const UPDATE_SCRIPT_NAME = 'factory:update';
 // `npx` so the script resolves in a fresh derived repo where @timekast/factory
@@ -36,6 +57,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 +71,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/gitattributes.js

@@ -0,0 +1,101 @@
+/**
+ * Surgical sync of the Factory's managed `.gitattributes` block into a derived
+ * project, mirroring the `package.json` script-insertion pattern (`package-json.ts`):
+ * the delimited block is replaced verbatim, everything outside it is preserved.
+ *
+ * Why not the lockfile/`track` engine: `.gitattributes` is dual-owned at the
+ * intra-file level (the Factory block + the dev's own rules share one file). The
+ * lockfile hashes whole files, so tracking it would read the dev's rules as a
+ * local edit and conflict on every update. Instead the block is synced as an
+ * idempotent post-apply step, outside `diffLockfiles`/`applyPlan`.
+ *
+ * The canonical block is the single SSOT: it is READ from the `.gitattributes`
+ * that ships in the staged tarball (see `extractManagedBlock`), never duplicated
+ * as a CLI constant. A derived repo's existing block is located by the
+ * `MANAGED_BLOCK_START` / `_END` sentinels (prefix match), so the descriptive
+ * comment copy can evolve without breaking detection.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { GITATTRIBUTES_FILE, MANAGED_BLOCK_END, MANAGED_BLOCK_START } from './constants.js';
+const isStart = (line) => line.trimStart().startsWith(MANAGED_BLOCK_START);
+const isEnd = (line) => line.trimStart().startsWith(MANAGED_BLOCK_END);
+/** Drop trailing all-whitespace lines (so appends don't pile up blank lines). */
+function stripTrailingEmpty(lines) {
+    const out = [...lines];
+    while (out.length > 0 && out[out.length - 1].trim() === '')
+        out.pop();
+    return out;
+}
+/**
+ * Extract the managed block (markers inclusive) from a `.gitattributes` content,
+ * or `null` if no start marker is present. Used on the well-formed staged source
+ * to obtain the canonical block to sync. If a start marker is found with no end
+ * marker, returns from start to EOF (defensive — the source is well-formed).
+ */
+export function extractManagedBlock(content) {
+    const lines = content.replace(/\r\n/g, '\n').split('\n');
+    const start = lines.findIndex(isStart);
+    if (start === -1)
+        return null;
+    let end = -1;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (isEnd(lines[i])) {
+            end = i;
+            break;
+        }
+    }
+    const slice = end === -1 ? lines.slice(start) : lines.slice(start, end + 1);
+    return slice.join('\n');
+}
+/**
+ * Sync `sourceBlock` (markers inclusive) into `<rootDir>/.gitattributes`,
+ * preserving every rule outside the managed block. The whole file is normalized
+ * to LF (it lives at repo root, outside `.claude/** text eol=lf`, so a source
+ * packed with CRLF on an autocrlf machine is normalized here). Idempotent:
+ * writes only when the bytes actually change.
+ *
+ *   - no file / empty file      → `created` (block only)
+ *   - file without a start marker → `inserted` (block appended after a blank line)
+ *   - start + end markers        → `updated` (content between markers replaced)
+ *   - start without end (dev clobbered half a line) → `updated`, regenerated
+ *     cleanly from start to EOF (NOT appended — avoids a dangling start marker)
+ */
+export function syncManagedBlock(rootDir, sourceBlock) {
+    const filePath = path.join(rootDir, GITATTRIBUTES_FILE);
+    const raw = existsSync(filePath) ? readFileSync(filePath, 'utf8') : '';
+    const block = sourceBlock.replace(/\r\n/g, '\n').replace(/\n+$/, '');
+    let result;
+    let action;
+    if (raw.trim() === '') {
+        result = `${block}\n`;
+        action = 'created';
+    }
+    else {
+        const lines = raw.replace(/\r\n/g, '\n').split('\n');
+        const start = lines.findIndex(isStart);
+        if (start === -1) {
+            const before = stripTrailingEmpty(lines);
+            result = `${before.join('\n')}\n\n${block}\n`;
+            action = 'inserted';
+        }
+        else {
+            // Replace from start to the end marker, or to EOF when the end marker is
+            // missing (malformed block → regenerate clean rather than append).
+            let end = lines.length - 1;
+            for (let i = start + 1; i < lines.length; i++) {
+                if (isEnd(lines[i])) {
+                    end = i;
+                    break;
+                }
+            }
+            const merged = [...lines.slice(0, start), ...block.split('\n'), ...lines.slice(end + 1)];
+            result = `${stripTrailingEmpty(merged).join('\n')}\n`;
+            action = 'updated';
+        }
+    }
+    if (result === raw)
+        return { action: 'unchanged' };
+    writeFileSync(filePath, result, 'utf8');
+    return { action };
+}

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.3.0",
   "description": "Public, thin CLI to bootstrap and maintain TimeKast Factory derived projects.",
   "type": "module",
   "license": "UNLICENSED",