@timekast/factory 1.0.0 → 1.2.0

package/dist/commands/doctor.js

@@ -16,8 +16,9 @@
  * No lockfile (pre-CLI repo) → delegate to the "run factory:update" advice, exit
  * 0, never abort (same pattern as `status` / the §8 edge case).
  */
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
+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';
@@ -42,29 +43,6 @@ export const A1_WARNING = 'Aviso de seguridad (A1): el boilerplate `src/` y sus
     'dependencia) NO llega por este canal. El canal de parches de `src/` es EPIC 2 ' +
     '(update agentico con merge inteligente), aún no disponible. Mantén `src/` y tus ' +
     'dependencias al día por tu cuenta mientras tanto.';
-/**
- * Recursively collect repo-relative POSIX paths of files under `.claude/`. Only
- * descends into `.claude/`; `src/` and everything else is invisible (design
- * §7.2). Mirrors the `update` engine's `collectClaudePaths`.
- */
-function collectClaudePaths(rootDir) {
-    const out = [];
-    const walk = (rel) => {
-        const abs = path.join(rootDir, rel);
-        if (!existsSync(abs))
-            return;
-        if (statSync(abs).isDirectory()) {
-            for (const entry of readdirSync(abs)) {
-                walk(path.posix.join(rel, entry));
-            }
-        }
-        else {
-            out.push(rel);
-        }
-    };
-    walk('.claude');
-    return out;
-}
 /**
  * Concatenate the body of the reserved "on-demand reference" section of CLAUDE.md
  * — the lines under a heading matching `ON_DEMAND_HEADING_RE`, until the next

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

@@ -33,11 +33,12 @@
  * `update` NEVER touches `src/` — files outside the lockfile/manifest are
  * invisible (design §9 out-of-scope).
  */
-import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 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 { diffLockfiles, hasLockfile, normalizeThenHash, planAutoRegister, readLockfile, writeLockfile, } from '../lib/lockfile.js';
@@ -64,30 +65,6 @@ async function acquireFromRelease(profile) {
     const manifest = validateStagedManifest(stagedDir, manifestRaw);
     return { stagedDir, manifest, tmpRoot };
 }
-/**
- * Recursively collect repo-relative paths of files under `.claude/` plus any
- * tracked root files the manifest references at the top level. Used both for
- * disk hashing and auto-register path-match. Only descends into `.claude/`;
- * `src/` and everything else is invisible (design §7.2).
- */
-function collectClaudePaths(rootDir) {
-    const out = [];
-    const walk = (rel) => {
-        const abs = path.join(rootDir, rel);
-        if (!existsSync(abs))
-            return;
-        if (statSync(abs).isDirectory()) {
-            for (const entry of readdirSync(abs)) {
-                walk(path.posix.join(rel, entry));
-            }
-        }
-        else {
-            out.push(rel);
-        }
-    };
-    walk('.claude');
-    return out;
-}
 /**
  * Hash the disk content (normalized) of every path in `paths` that exists.
  * A missing file is simply absent from the returned map.

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/claude-paths.js

@@ -0,0 +1,68 @@
+/**
+ * Collect the repo-relative POSIX paths of files under `.claude/`, EXCLUDING
+ * gitignored ones. Shared by `update` (legacy auto-register ambiguous report)
+ * and `doctor` (orphan report) so neither flags a dev-local, gitignored file
+ * (`settings.local.json`, `transitions/`, `.DS_Store`) as "ambiguous"/"orphan" —
+ * those are never kit-managed, so surfacing them is pure noise.
+ *
+ * Only descends into `.claude/`; `src/` and everything else is invisible
+ * (design §7.2).
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+/**
+ * Fallback ignore set, used only when `git check-ignore` is unavailable (no git
+ * binary, or the dir is not a git repo). Mirrors the kit's own `.gitignore`
+ * entries for `.claude/`. The git path is authoritative when present.
+ */
+const IGNORE_FALLBACK_RE = /(^|\/)(\.DS_Store|settings\.local\.json)$|(^|\/)transitions\//;
+/** Recursively gather repo-relative POSIX paths of files under `.claude/`. */
+function walkClaude(rootDir) {
+    const out = [];
+    const walk = (rel) => {
+        const abs = path.join(rootDir, rel);
+        if (!existsSync(abs))
+            return;
+        if (statSync(abs).isDirectory()) {
+            for (const entry of readdirSync(abs))
+                walk(path.posix.join(rel, entry));
+        }
+        else {
+            out.push(rel);
+        }
+    };
+    walk('.claude');
+    return out;
+}
+/**
+ * Drop the gitignored paths from `paths`. Uses `git check-ignore --stdin` (the
+ * authoritative source — respects nested `.gitignore`, negations, etc.); falls
+ * back to `IGNORE_FALLBACK_RE` when git is missing or the dir is not a repo.
+ *
+ * `git check-ignore` exit codes: 0 = some paths matched (printed), 1 = none
+ * matched (empty output), 128 = error / not a repo. `spawnSync` does not throw,
+ * so 0 and 1 both yield usable stdout; >1 or a spawn error → fallback.
+ */
+function dropGitignored(rootDir, paths) {
+    if (paths.length === 0)
+        return paths;
+    const res = spawnSync('git', ['-C', rootDir, 'check-ignore', '--stdin'], {
+        input: paths.join('\n'),
+        encoding: 'utf8',
+    });
+    if (res.error || res.status === null || res.status > 1) {
+        return paths.filter((p) => !IGNORE_FALLBACK_RE.test(p));
+    }
+    const ignored = new Set((res.stdout || '')
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean));
+    return paths.filter((p) => !ignored.has(p));
+}
+/**
+ * Repo-relative POSIX paths of NON-gitignored files under `.claude/`.
+ */
+export function collectClaudePaths(rootDir) {
+    return dropGitignored(rootDir, walkClaude(rootDir));
+}

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,9 +30,30 @@ export const LOCKFILE_FILE = 'lockfile.json';
  * exists on disk (path-match path). See `diffLockfiles` + the install commands.
  */
 export const CLAUDE_MD_FILE = 'CLAUDE.md';
-/** The script the CLI injects into a derived project's package.json. */
+/** 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
 // is NOT a dependency (B3): a bare `@timekast/factory update` would be
 // "command not found". npx resolves the published package on demand.
 export const UPDATE_SCRIPT_CMD = 'npx @timekast/factory update';
+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
+ * by script name → command. `factory:update` is the primary (drives the install
+ * messaging); `doctor`/`status` are read-only diagnostics with no other alias.
+ */
+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/package-json.js

@@ -8,7 +8,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { CLIError } from './cli-error.js';
-import { PROFILES, UPDATE_SCRIPT_CMD, UPDATE_SCRIPT_NAME } from './constants.js';
+import { FACTORY_SCRIPTS, PROFILES, UPDATE_SCRIPT_NAME } from './constants.js';
 /**
  * Auto-detect the profile to install into an existing repo from its
  * `package.json`: a `factoryVersion` field means the repo was born from the
@@ -58,26 +58,40 @@ export function parsePackageJson(raw) {
     }
 }
 /**
- * Pure core of the script insertion: mutate `pkg.scripts` in place to ensure
- * `factory:update` exists, never overwriting a divergent value. Shared by
+ * Pure core of the script insertion: mutate `pkg.scripts` in place to ensure ALL
+ * `factory:*` convenience scripts exist (`update` / `doctor` / `status`), adding
+ * each if missing and NEVER overwriting a divergent value (§7.4). Shared by
  * `applyPackageJsonEdits` (the `new` flow) and `insertFactoryUpdateScript`
- * (the `update` flow) so both follow the same §7.4 rule.
+ * (the `update` flow). Returns whether anything changed (so the caller writes
+ * only on a real edit) + the result for the primary `factory:update` script
+ * (which drives the install messaging).
  */
-function ensureUpdateScript(pkg) {
+function ensureFactoryScripts(pkg) {
     const scripts = pkg.scripts ?? {};
-    const existing = scripts[UPDATE_SCRIPT_NAME];
     pkg.scripts = scripts;
-    if (existing === undefined) {
-        scripts[UPDATE_SCRIPT_NAME] = UPDATE_SCRIPT_CMD;
-        return { action: 'added' };
-    }
-    if (existing === UPDATE_SCRIPT_CMD) {
-        return { action: 'already-correct' };
+    let changed = false;
+    let primary = { action: 'already-correct' };
+    for (const [name, cmd] of Object.entries(FACTORY_SCRIPTS)) {
+        const existing = scripts[name];
+        let result;
+        if (existing === undefined) {
+            scripts[name] = cmd;
+            changed = true;
+            result = { action: 'added' };
+        }
+        else if (existing === cmd) {
+            result = { action: 'already-correct' };
+        }
+        else {
+            result = { action: 'conflict', existingValue: existing };
+        }
+        if (name === UPDATE_SCRIPT_NAME)
+            primary = result;
     }
-    return { action: 'conflict', existingValue: existing };
+    return { changed, primary };
 }
 /**
- * Rename `package.json.name` and ensure the `factory:update` script exists,
+ * Rename `package.json.name` and ensure the `factory:*` scripts exist,
  * preserving everything else. Returns the serialized document (with the
  * original indentation + trailing newline).
  *
@@ -88,31 +102,32 @@ export function applyPackageJsonEdits(raw, name) {
     const indent = detectIndent(raw);
     const pkg = parsePackageJson(raw);
     pkg.name = name;
-    const result = ensureUpdateScript(pkg);
+    const { primary } = ensureFactoryScripts(pkg);
     const content = `${JSON.stringify(pkg, null, indent)}\n`;
-    return { content, scriptAlreadyPresent: result.action === 'conflict' };
+    return { content, scriptAlreadyPresent: primary.action === 'conflict' };
 }
 /**
- * Surgically ensure the `factory:update` script exists in the `package.json` at
- * `pkgPath` (design §7.4). Reads, mutates only the single key, and re-serializes
- * with the original indentation + trailing newline. NEVER overwrites a divergent
- * value and NEVER touches `name`, deps, or any other script.
+ * Surgically ensure the `factory:*` scripts (`update` / `doctor` / `status`)
+ * exist in the `package.json` at `pkgPath` (design §7.4). Reads, mutates only
+ * those keys, and re-serializes with the original indentation + trailing
+ * newline. NEVER overwrites a divergent value and NEVER touches `name`, deps,
+ * or any other script.
  *
- * Writes the file only when something actually changed (`added`); for
- * `already-correct` and `conflict` the file is left byte-identical.
+ * Writes the file only when at least one script was added; if all are already
+ * present (correct or divergent) the file is left byte-identical.
  *
  * @param pkgPath Absolute path to the derived project's `package.json`.
- * @returns What happened, plus the existing value when it conflicts.
+ * @returns The result for the primary `factory:update` script (+ existing value on conflict).
  */
 export function insertFactoryUpdateScript(pkgPath) {
     const raw = readFileSync(pkgPath, 'utf8');
     const indent = detectIndent(raw);
     const pkg = parsePackageJson(raw);
-    const result = ensureUpdateScript(pkg);
-    if (result.action === 'added') {
+    const { changed, primary } = ensureFactoryScripts(pkg);
+    if (changed) {
         writeFileSync(pkgPath, `${JSON.stringify(pkg, null, indent)}\n`, 'utf8');
     }
-    return result;
+    return primary;
 }
 /**
  * Surgically set the derived project's `package.json.agentKitVersion` to the

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