@timekast/factory 2.0.1 → 2.1.0

package/dist/commands/add.js

@@ -38,7 +38,7 @@ import { CLAUDE_MD_FILE, PROFILES } from '../lib/constants.js';
 import { hasLockfile, writeInitialLockfile } from '../lib/lockfile.js';
 import { detectProfile, maintainKitScripts } from '../lib/package-json.js';
 import { runPreflight } from '../lib/preflight.js';
-import { detectRepo } from '../lib/repo-detection.js';
+import { detectRepo, resolveBrainRoot } from '../lib/repo-detection.js';
 import { downloadProfileTarball, stageProfileTarball } from '../lib/unpack.js';
 import { reportPkgMutations, runUpdate } from './update.js';
 /** Message shown when `add` runs outside any git repo context. */
@@ -56,11 +56,12 @@ export async function runAdd(flags = { core: false, full: false }) {
     //    network call or write — nothing is touched when there is no repo. The
     //    brain lives at the REPO ROOT, so all gating + install target `root`, not
     //    `cwd` — running `add` from a subdir must not plant a nested second brain.
-    const { hasRepo, repoRoot } = detectRepo(cwd);
+    const { hasRepo } = detectRepo(cwd);
     if (!hasRepo) {
         throw new CLIError(NO_REPO_MESSAGE);
     }
-    const root = repoRoot ?? cwd;
+    // Same target guard as `update`: never a root that is `~` or contains it.
+    const root = resolveBrainRoot(cwd);
     // 2. Gate on a pre-existing brain (checked at the repo root, not cwd). `add` is
     //    for a repo WITHOUT one; anything else routes to `update` so the raw
     //    `applyPlan` install never clobbers an old `.claude/` (leaving orphans, no

package/dist/commands/provision.js

@@ -30,6 +30,7 @@ import { execa } from 'execa';
 import prompts from 'prompts';
 import { FACTORY_ORG } from '../lib/constants.js';
 import { CLIError } from '../lib/cli-error.js';
+import { sendingDomainOf } from '../lib/email-from.js';
 import { apexZoneOf, CloudflareApiError, CLOUDFLARE_API_BASE, absoluteRecordName, deleteDnsRecord, getDnsRecord, ensureCnameRecord, ensureDnsRecord, ensureUnproxiedRecord, resolveZoneForDomain, findCnameRecord, resolveZoneId, resolveZoneIdForName, resolveZoneIdForDomain, CNAME_VERCEL_TARGET, TIMEKAST_ZONE_NAME, provisionDomains, existingProvisionDomains, ORG_ZONE_NAMES, } from '../lib/cloudflare-api.js';
 import { createDevelopBranch, createNeonProject, createProjectApiKey, deleteNeonApiKeysByName, getNeonProjectOrg, listNeonOrgs, resolveNeonOrg, deleteNeonProject, getConnectionUri, isNeonKeyFamily, listNeonApiKeys, newestNeonFamilyKey, listNeonBranches, listNeonProjects, NeonApiError, NeonApiKeyListError, revokeNeonApiKey, rotatedNeonKeyName, NEON_API_BASE, NEON_DEVELOP_BRANCH, } from '../lib/neon-api.js';
 import { createBacklogProject, deleteBacklogProject, mintBacklogKey, BacklogApiError, } from '../lib/backlog-api.js';
@@ -1928,9 +1929,7 @@ const RESEND_KEY_RESUME_HINT = 'repite la corrida con `--resume` y `dns` en `--s
  */
 function noVaultMintDomain(state) {
     const client = state.dns?.clientDomainStatus === 'live' ? state.dns.clientDomain : undefined;
-    return client
-        ? mailDomainFor(client)
-        : PROVISION_EMAIL_FROM.slice(PROVISION_EMAIL_FROM.indexOf('@') + 1);
+    return client ? mailDomainFor(client) : sendingDomainOf(PROVISION_EMAIL_FROM);
 }
 /**
  * NO-vault path (F9 — the rail's team key never reaches a deploy): the project's OWN send-only
@@ -2029,7 +2028,7 @@ async function ensureProjectResendKey(rootDir, state, ctx, rail, fetchImpl, pers
         return null;
     }
     const sender = vaultSender(main);
-    const domain = sender.slice(sender.indexOf('@') + 1);
+    const domain = sendingDomainOf(sender);
     // SYNC-001: a key this one REPLACES is revoked only once the syncs delivered the new one — the
     // marker is each deploy sync's last job (Vercel or Railway) before the write (taken only when there is a key to
     // revoke later). Taken BEFORE the mint: a vault that cannot list its syncs stops the run here,
@@ -7545,8 +7544,19 @@ export const RAILWAY_ENVIRONMENTS = [
 ];
 /** The port the app listens on in Railway: the vault writes it as `PORT` (Decision 10). */
 export const RAILWAY_APP_PORT = 3000;
-/** The public health route the probe asks, and the service's `healthcheckPath` once it answers. */
-export const RAILWAY_HEALTH_PATH = '/api/health';
+/**
+ * The public liveness route the probe asks, and the service's `healthcheckPath` once it answers.
+ * It touches no database: Railway only asks whether the process started, and a public route that
+ * queries Neon lets any bot keep it from autosuspending.
+ */
+export const RAILWAY_HEALTH_PATH = '/api/health/live';
+/**
+ * The fallback for a derivative whose `src/` predates the liveness route but applied the earlier
+ * retrofit, which made the DB-backed `/api/health` public. Asked only when `/api/health/live`
+ * answers 404, so the CLI tolerates that frozen `src/` (BR-FACTORY-006) instead of leaving its
+ * healthcheck off.
+ */
+export const RAILWAY_LEGACY_HEALTH_PATH = '/api/health';
 /**
  * The service's commands, with the vault wrapper OFF explicitly (Decision 11): in Railway the env
  * already holds what the sync delivered. Railway runs build → pre-deploy → start, so the build still
@@ -7830,14 +7840,14 @@ async function waitForRailwayDeployment(client, role, deploymentId, seams) {
     }
 }
 /**
- * One ANONYMOUS request to `/api/health` through Railway's own domain of an environment: no
- * cookie, no token, redirects not followed (a redirect to the login is "not public"). 200 → `ok`;
- * 401/403/3xx → `not-public`; anything else, or no answer in time → `down`.
+ * One ANONYMOUS request to `path` (default `/api/health/live`) through Railway's own domain of an
+ * environment: no cookie, no token, redirects not followed (a redirect to the login is "not
+ * public"). 200 → `ok`; 401/403/3xx → `not-public`; anything else, or no answer in time → `down`.
  */
-export async function probeRailwayHealth(domain, fetchImpl) {
+export async function probeRailwayHealth(domain, fetchImpl, path = RAILWAY_HEALTH_PATH) {
     let status;
     try {
-        const response = await fetchImpl(`https://${domain}${RAILWAY_HEALTH_PATH}`, {
+        const response = await fetchImpl(`https://${domain}${path}`, {
             method: 'GET',
             redirect: 'manual',
             signal: AbortSignal.timeout(RAILWAY_PROBE_TIMEOUT_MS),
@@ -7867,6 +7877,8 @@ function railwayProbeFetch(seams) {
  * Probe each environment whose healthcheck is not `on` yet; with 200, set `healthcheckPath` there
  * and mark it `on`, otherwise mark it `pending` and print the retrofit instruction. Never fails
  * the alta: a derivative whose `src/` lacks the public route keeps deploying without healthcheck.
+ * A 404 on the liveness route falls back to the legacy public `/api/health` (see
+ * `RAILWAY_LEGACY_HEALTH_PATH`); with 200 there it is used, and the guide to move off it is named.
  */
 async function settleRailwayHealthchecks(client, rw, seams, persist) {
     const probeFetch = railwayProbeFetch(seams);
@@ -7877,15 +7889,25 @@ async function settleRailwayHealthchecks(client, rw, seams, persist) {
         if (!domain)
             continue;
         const result = await probeRailwayHealth(domain, probeFetch);
-        if (result.kind === 'ok') {
+        let path = RAILWAY_HEALTH_PATH;
+        if (result.kind === 'down' && result.status === 404) {
+            const legacy = await probeRailwayHealth(domain, probeFetch, RAILWAY_LEGACY_HEALTH_PATH);
+            if (legacy.kind === 'ok')
+                path = RAILWAY_LEGACY_HEALTH_PATH;
+        }
+        if (result.kind === 'ok' || path === RAILWAY_LEGACY_HEALTH_PATH) {
             await client.updateServiceInstance({
                 serviceId: rw.serviceId,
                 environmentId: rw.environments?.[role],
-                settings: { healthcheckPath: RAILWAY_HEALTH_PATH },
+                settings: { healthcheckPath: path },
             });
             rw.healthcheck = { ...rw.healthcheck, [role]: 'on' };
             persist();
-            console.log(`  ✔ healthcheck de \`${role}\` activado (\`${RAILWAY_HEALTH_PATH}\` respondió 200)`);
+            console.log(`  ✔ healthcheck de \`${role}\` activado (\`${path}\` respondió 200)`);
+            if (path === RAILWAY_LEGACY_HEALTH_PATH) {
+                console.warn(`  ℹ Este \`src/\` no tiene \`${RAILWAY_HEALTH_PATH}\`; uso \`${path}\`, que es pública y consulta la base ` +
+                    `(cualquier sonda anónima la despierta). Para pasarte a la ruta sin base: §5 de \`${RAILWAY_HEALTH_RETROFIT_GUIDE}\`.`);
+            }
             continue;
         }
         rw.healthcheck = { ...rw.healthcheck, [role]: 'pending' };

package/dist/commands/update.js

@@ -52,7 +52,7 @@ import { printProvisionPointer } from '../lib/provision-pointer.js';
 import { printRetrofitReminder } from '../lib/retrofit-reminder.js';
 import { hasProvisionState } from '../lib/provision-state.js';
 import { loginCommand } from '../lib/rail.js';
-import { detectRepo } from '../lib/repo-detection.js';
+import { resolveBrainRoot } from '../lib/repo-detection.js';
 import { downloadBetaProfileTarball, downloadProfileTarball, stageProfileTarball, } from '../lib/unpack.js';
 /** Parse `update`'s argv slice into flags. Unknown flags are ignored here. */
 export function parseUpdateFlags(argv) {
@@ -795,8 +795,9 @@ export async function maybeOfferEmptyE2EBranch(rootDir, flags, opts = {}) {
 export async function runUpdate(flags, deps = {}) {
     // Operate on the REPO ROOT (the brain + lockfile live there), not cwd — running
     // `update` from a subdir of a managed repo must not miss the lockfile and
-    // legacy-register a second nested brain (consistency with `add`).
-    const rootDir = detectRepo(process.cwd()).repoRoot ?? process.cwd();
+    // legacy-register a second nested brain (consistency with `add`). Outside a repo,
+    // or with a root that is `~` or an ancestor of it, it stops before anything else.
+    const rootDir = resolveBrainRoot(process.cwd());
     // Mutually-exclusive flag validation FIRST — before --verify/--resume
     // short-circuit, so an invalid combination is always rejected (not silently
     // honored by verify/resume).

package/dist/commands/vault.js

@@ -34,6 +34,7 @@ import path from 'node:path';
 import { execa } from 'execa';
 import prompts from 'prompts';
 import { CLIError } from '../lib/cli-error.js';
+import { sendingDomainOf } from '../lib/email-from.js';
 import { WITH_VAULT_SCRIPT_FILE } from '../lib/constants.js';
 import { parseEnvBody } from '../lib/env-wizard.js';
 import { hasLockfile, readLockfile } from '../lib/lockfile.js';
@@ -53,12 +54,14 @@ import { computeStatus } from './status.js';
 // ---------------------------------------------------------------------------
 // Help + flags
 // ---------------------------------------------------------------------------
+/** The vault (Infisical) refuses a project slug shorter than this. */
+export const VAULT_SLUG_MIN_LENGTH = 5;
 /** What `factory vault` prints without a subcommand. */
 export const VAULT_HELP = `
 factory vault — la bóveda de secretos de la organización (fx-secrets-vault).
 
 Uso:
-  factory vault adopt [--apply] [--json] [--team=<id>] [--vercel-project <id>]
+  factory vault adopt [--apply] [--json] [--team=<id>] [--vercel-project <id>] [--slug <slug>]
   factory vault adopt --decline
   factory vault sync railway --project <id> --service <id> --env <main|develop> [--railway-env <nombre>]
   factory vault deploys [--deploy <slug>] [--apply] [--yes]
@@ -83,6 +86,10 @@ Subcomandos:
                  Con varios proyectos de Vercel conectados al repo, elige el que queda como
                  proyecto principal (tiene que ser uno de ellos). Los demás despliegues se
                  operan después con \`factory vault deploys\`.
+    --slug <slug>
+                 Slug del proyecto en la bóveda (mínimo ${VAULT_SLUG_MIN_LENGTH} caracteres). Default: el
+                 que registra .timekast/provision.json, si no el proyecto de Vercel, si no
+                 el repo de origin, y sólo al final el nombre del directorio.
     --decline    Registra en .timekast/provision.json que este repo NO entra a la bóveda:
                  sigue con .env.local y env:push, y doctor deja de proponerlo. No toca nada
                  más ni consulta ningún servicio. Adoptar después sigue siendo posible.
@@ -140,15 +147,32 @@ export function parseVaultAdoptFlags(argv) {
             }
             flags.vercelProject = value.trim();
         }
+        else if (arg === '--slug' || arg.startsWith('--slug=')) {
+            let value;
+            if (arg.startsWith('--slug='))
+                value = arg.slice('--slug='.length);
+            else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--')) {
+                value = argv[i + 1];
+                i += 1;
+            }
+            if (value === undefined || value.trim() === '') {
+                throw new CLIError('`--slug` necesita el slug del proyecto en la bóveda.');
+            }
+            flags.slug = value.trim().toLowerCase();
+        }
         else {
-            throw new CLIError(`Opción desconocida para \`factory vault adopt\`: \`${arg}\`. Uso: \`factory vault adopt [--apply] [--json] [--team=<id>] [--vercel-project <id>]\` o \`factory vault adopt --decline\`.`);
+            throw new CLIError(`Opción desconocida para \`factory vault adopt\`: \`${arg}\`. Uso: \`factory vault adopt [--apply] [--json] [--team=<id>] [--vercel-project <id>] [--slug <slug>]\` o \`factory vault adopt --decline\`.`);
         }
     }
     if (flags.apply && flags.json) {
         throw new CLIError('`--json` es sólo para el plan (sin `--apply`).');
     }
     if (flags.decline &&
-        (flags.apply || flags.json || flags.team !== undefined || flags.vercelProject !== undefined)) {
+        (flags.apply ||
+            flags.json ||
+            flags.team !== undefined ||
+            flags.vercelProject !== undefined ||
+            flags.slug !== undefined)) {
         throw new CLIError('`--decline` va solo: registra que el repo no entra a la bóveda, sin plan ni `--apply`.');
     }
     return flags;
@@ -937,9 +961,19 @@ async function prepareAdoption(rootDir, flags, deps) {
         slug = fromConfig;
     }
     else {
-        slug = (realField(target?.slug) ?? vercelProject?.name ?? path.basename(rootDir)).toLowerCase();
+        // The origin repo's name comes before the directory's: a worktree or a renamed checkout
+        // would otherwise name the vault project after the folder.
+        slug = (flags.slug ??
+            realField(target?.slug) ??
+            vercelProject?.name ??
+            repo?.split('/')[1] ??
+            path.basename(rootDir)).toLowerCase();
     }
     assertValidSubdomainSlug(slug);
+    if (slug.length < VAULT_SLUG_MIN_LENGTH) {
+        throw new CLIError(`El slug \`${slug}\` tiene menos de ${VAULT_SLUG_MIN_LENGTH} caracteres y la bóveda no acepta ` +
+            `crear un proyecto así. Elige uno con \`--slug <slug>\` (p. ej. \`${slug}-web\`). No escribí nada.`);
+    }
     const railwayToken = await rail.getOptional(RAILWAY_TOKEN_KEY);
     if (!railwayToken) {
         console.warn('⚠ No hay `RAILWAY_TOKEN` en `rail-timekast`: no inventarié Railway. Si este repo despliega ahí, ' +
@@ -981,7 +1015,7 @@ async function prepareAdoption(rootDir, flags, deps) {
         values.preview.get('EMAIL_FROM') ??
         values.local.get('EMAIL_FROM') ??
         PROVISION_EMAIL_FROM;
-    const resendDomain = sender.slice(sender.indexOf('@') + 1);
+    const resendDomain = sendingDomainOf(sender);
     const client = deps.vaultClient ?? createVaultClient();
     const githubSecretNames = repo
         ? [...(await (deps.listGithubSecretNames ?? ghSecretNames)(repo))].sort()

package/dist/lib/claude-md.js

@@ -224,8 +224,10 @@ export function classifyClaudeMd(opts) {
         return { case: 'A', action: 'none', uncovered: [] };
     }
     const uncovered = uncoveredKitRules(content, kitRules);
-    if (uncovered.length > 0)
-        return { case: 'C', action: 'none', uncovered };
+    // `skip-core` on case C only shapes the advice: `core` has no INDEX to point at.
+    if (uncovered.length > 0) {
+        return { case: 'C', action: profile === 'core' ? 'skip-core' : 'none', uncovered };
+    }
     if (hasIndexImport(content))
         return { case: 'B', action: 'already-present', uncovered: [] };
     // The `core` profile does not ship `.claude/rules/INDEX.md` at all (it resolves its
@@ -296,7 +298,10 @@ export function reportClaudeMd(assessment, mode, inserted = true) {
     if (kind === 'C') {
         console.log(`\n\`${CLAUDE_MD_FILE}\` (caso C — necesita revisión manual): lo editaste y le faltan rules del kit ` +
             `en los imports: ${uncovered.join(', ')}.`);
-        console.log(`  No se tocó nada. Agrega \`${RULES_INDEX_IMPORT}\` a mano (importa todas) o repón los imports que falten.`);
+        console.log(action === 'skip-core'
+            ? `  No se tocó nada. Repón a mano los imports que falten (\`@<ruta>\` por cada una); ` +
+                `el perfil \`core\` no incluye \`${RULES_INDEX_PATH}\`.`
+            : `  No se tocó nada. Agrega \`${RULES_INDEX_IMPORT}\` a mano (importa todas) o repón los imports que falten.`);
         return;
     }
     // Case B — edited outside the kit's zone.

package/dist/lib/email-from.js

@@ -0,0 +1,30 @@
+/**
+ * The sending domain of an `EMAIL_FROM` value — the domain a project's Resend key is limited to.
+ *
+ * `EMAIL_FROM` comes in two shapes, and a live deploy carries either: the bare address the kit
+ * writes (`noreply@updates.timekast.com`) and the RFC 5322 display-name form a team sets so the
+ * inbox shows a name (`TimeKast Calendar <noreply@tk-cal.com>`). Taking everything after the `@`
+ * of the raw value turns the second one into `tk-cal.com>` — a domain Resend never lists, so
+ * `vault adopt --apply` aborted on a perfectly valid sender.
+ *
+ * Rule: the address is the part inside the LAST `<…>` when there is one, else the whole value;
+ * the domain is what follows its LAST `@`, trimmed and lower-cased (DNS names are
+ * case-insensitive and Resend lists them lower-case). No `@` at all → `''`, which matches no
+ * Resend domain, so the caller's "domain not registered" path stops the run instead of minting
+ * a key for a guessed domain.
+ *
+ * 🔒 TOTAL (never throws): it runs on values read from a deploy, which the CLI does not control.
+ */
+export function sendingDomainOf(emailFrom) {
+    const value = emailFrom.trim();
+    const open = value.lastIndexOf('<');
+    const close = value.lastIndexOf('>');
+    const address = open !== -1 && close > open ? value.slice(open + 1, close) : value;
+    const at = address.lastIndexOf('@');
+    return at === -1
+        ? ''
+        : address
+            .slice(at + 1)
+            .trim()
+            .toLowerCase();
+}

package/dist/lib/repo-detection.js

@@ -9,8 +9,10 @@
  * is a valid context (DIST-004 §8). `add` installs in the CWD, not the repo
  * root — `repoRoot` is informational (e.g. monorepo with `.git/` in an ancestor).
  */
-import { existsSync } from 'node:fs';
+import { existsSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
 import path from 'node:path';
+import { CLIError } from './cli-error.js';
 /**
  * Detect whether `cwd` (or any ancestor) is inside a git repository.
  *
@@ -30,3 +32,42 @@ export function detectRepo(cwd) {
     }
     return { hasRepo: false, repoRoot: null };
 }
+/**
+ * The repo root a brain-writing command (`update`, `add`) may install into, or a
+ * `CLIError` before anything is read, downloaded or written.
+ *
+ * Refuses outside a git repo (no silent fallback to `cwd`) and refuses a root that
+ * is the home directory or one of its ancestors: run from `~`, or from a `~` that
+ * versions dotfiles in a `~/.git`, the manifest would land on `~/.claude`. No flag
+ * skips it — `--yes` only answers prompts, it never widens the target.
+ *
+ * @param cwd Directory the command was run from.
+ * @param home The user's home directory (injectable for tests).
+ */
+export function resolveBrainRoot(cwd, home = homedir()) {
+    const { repoRoot } = detectRepo(cwd);
+    if (!repoRoot) {
+        throw new CLIError('No hay repositorio git aquí. Corre el comando desde la raíz de tu proyecto ' +
+            '(o `git init` primero, o `factory new` para crear uno desde cero). No toqué nada.');
+    }
+    // Compared through symlinks: `cwd` arrives resolved (`/private/var/...` on macOS)
+    // while `HOME` may name the same folder by its link.
+    const root = path.resolve(repoRoot);
+    // Home is at or under the root unless the way from root to home climbs out first.
+    const relative = path.relative(realOrResolved(root), realOrResolved(home));
+    const homeOutsideRoot = relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
+    if (!homeOutsideRoot) {
+        throw new CLIError(`La raíz del repo es \`${root}\`, que es tu carpeta personal o la contiene. ` +
+            'El kit solo se instala dentro de un proyecto: corre el comando desde la carpeta del proyecto. No toqué nada.');
+    }
+    return root;
+}
+/** `realpath` of `p`, or its plain resolution when it does not exist. */
+function realOrResolved(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}

package/package.json

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