@ornexus/neocortex 4.60.67 → 4.60.68

package/packages/client/dist/effects/invoke-effect-gateways.js

@@ -1 +1,62 @@
-import{assertDeclaredNetworkTransport as i,resolveClosedProcessProfile as a,StrictReadOnlyError as c}from"../../../shared/dist/strict-readonly.js";function d(t,e,r){const o={phase:"client-preflight",domain:"client-persistence",category:r,operation:"update"};return Object.freeze({get:n=>e.get(n),set:(n,s,u)=>t.executeAsync(o,()=>e.set(n,s,u),async()=>{}),clear:()=>t.executeAsync(o,()=>e.clear(),async()=>{})})}function f(t,e,r,o,n="engine"){const s=a(e,r);return t.execute({phase:n,domain:"external-effect",category:"process",operation:"spawn"},()=>o(s),()=>({status:null,stdout:"",stderr:"",projected:!0}))}function h(t,e,r,o,n="engine"){const s=a(e,r);return t.execute({phase:n,domain:"external-effect",category:"git",operation:"spawn"},()=>o(s),()=>({status:null,stdout:"",stderr:"",projected:!0}))}function g(t,e){return t.execute({phase:"client-preflight",domain:"client-persistence",category:"scheduler-session",operation:"create"},()=>(e(),!0),()=>!1)}function y(t,e,r,o){if(!l(e))throw new c("readonly-physical-boundary-unsafe","boundary");return t.execute({phase:"client-preflight",domain:"external-effect",category:"process",operation:"spawn"},r,o)}function l(t){if(t.args.length>8||t.args.some(n=>n.length>512||/[\r\n\0]/u.test(n)))return!1;const e=t.args,r=n=>!!(n&&/^[A-Za-z0-9_.:@-]{1,180}$/u.test(n)),o=n=>!!(n&&(n.startsWith("/")||/^[A-Za-z]:[\\/]/u.test(n))&&!n.split(/[\\/]/u).includes(".."));return t.command==="systemctl"?e[0]==="--user"&&(e.length===2&&e[1]==="daemon-reload"||e.length===4&&e[1]==="enable"&&e[2]==="--now"&&r(e[3])||e.length===3&&(e[1]==="start"||e[1]==="stop")&&r(e[2])||e.length===4&&e[1]==="status"&&r(e[2])&&e[3]==="--no-pager"):t.command==="launchctl"?e.length===3&&(e[0]==="load"||e[0]==="unload")&&e[1]==="-w"&&o(e[2])||e.length===2&&e[0]==="list"&&r(e[1]):t.command==="schtasks"?e.length===6&&e[0]==="/Create"&&e[1]==="/TN"&&r(e[2])&&e[3]==="/XML"&&o(e[4])&&e[5]==="/F"||e.length===3&&(e[0]==="/Run"||e[0]==="/End")&&e[1]==="/TN"&&r(e[2])||e.length===5&&e[0]==="/Query"&&e[1]==="/TN"&&r(e[2])&&e[3]==="/FO"&&e[4]==="LIST":t.command==="crontab"&&e.length===1&&e[0]==="-l"}async function x(t,e){return i(t),e()}async function m(t,e,r,o){if(e!=="secondary-mutation")throw new c("readonly-physical-boundary-unsafe","boundary");return t.executeAsync({phase:"client-preflight",domain:"external-effect",category:"network-mutation",operation:"send"},r,o)}export{d as createCapabilityCache,h as executeClosedGitInspection,f as executeClosedProcess,x as executeInvokeQueryTransport,g as executeSchedulerManifestWrite,y as executeSchedulerProcess,m as executeSecondaryNetworkMutation};
+import { assertDeclaredNetworkTransport, resolveClosedProcessProfile, StrictReadOnlyError, } from '../../../shared/dist/strict-readonly.js';
+export function createCapabilityCache(authority, delegate, category) {
+    const descriptor = { phase: 'client-preflight', domain: 'client-persistence', category, operation: 'update' };
+    return Object.freeze({
+        get: (key) => delegate.get(key),
+        set: (key, value, ttlMs) => authority.executeAsync(descriptor, () => delegate.set(key, value, ttlMs), async () => undefined),
+        clear: () => authority.executeAsync(descriptor, () => delegate.clear(), async () => undefined),
+    });
+}
+export function executeClosedProcess(authority, profileName, cwd, writer, phase = 'engine') {
+    const profile = resolveClosedProcessProfile(profileName, cwd);
+    return authority.execute({ phase, domain: 'external-effect', category: 'process', operation: 'spawn' }, () => writer(profile), () => ({ status: null, stdout: '', stderr: '', projected: true }));
+}
+export function executeClosedGitInspection(authority, profileName, cwd, writer, phase = 'engine') {
+    const profile = resolveClosedProcessProfile(profileName, cwd);
+    return authority.execute({ phase, domain: 'external-effect', category: 'git', operation: 'spawn' }, () => writer(profile), () => ({ status: null, stdout: '', stderr: '', projected: true }));
+}
+export function executeSchedulerManifestWrite(authority, writer) {
+    return authority.execute({ phase: 'client-preflight', domain: 'client-persistence', category: 'scheduler-session', operation: 'create' }, () => { writer(); return true; }, () => false);
+}
+export function executeSchedulerProcess(authority, command, writer, projected) {
+    if (!isClosedSchedulerCommand(command)) {
+        throw new StrictReadOnlyError('readonly-physical-boundary-unsafe', 'boundary');
+    }
+    return authority.execute({ phase: 'client-preflight', domain: 'external-effect', category: 'process', operation: 'spawn' }, writer, projected);
+}
+function isClosedSchedulerCommand(command) {
+    if (command.args.length > 8
+        || command.args.some((arg) => arg.length > 512 || /[\r\n\0]/u.test(arg)))
+        return false;
+    const args = command.args;
+    const safeName = (value) => Boolean(value && /^[A-Za-z0-9_.:@-]{1,180}$/u.test(value));
+    const safePath = (value) => Boolean(value
+        && (value.startsWith('/') || /^[A-Za-z]:[\\/]/u.test(value))
+        && !value.split(/[\\/]/u).includes('..'));
+    if (command.command === 'systemctl') {
+        return args[0] === '--user' && ((args.length === 2 && args[1] === 'daemon-reload')
+            || (args.length === 4 && args[1] === 'enable' && args[2] === '--now' && safeName(args[3]))
+            || (args.length === 3 && (args[1] === 'start' || args[1] === 'stop') && safeName(args[2]))
+            || (args.length === 4 && args[1] === 'status' && safeName(args[2]) && args[3] === '--no-pager'));
+    }
+    if (command.command === 'launchctl') {
+        return (args.length === 3 && (args[0] === 'load' || args[0] === 'unload') && args[1] === '-w' && safePath(args[2]))
+            || (args.length === 2 && args[0] === 'list' && safeName(args[1]));
+    }
+    if (command.command === 'schtasks') {
+        return (args.length === 6 && args[0] === '/Create' && args[1] === '/TN' && safeName(args[2]) && args[3] === '/XML' && safePath(args[4]) && args[5] === '/F')
+            || (args.length === 3 && (args[0] === '/Run' || args[0] === '/End') && args[1] === '/TN' && safeName(args[2]))
+            || (args.length === 5 && args[0] === '/Query' && args[1] === '/TN' && safeName(args[2]) && args[3] === '/FO' && args[4] === 'LIST');
+    }
+    return command.command === 'crontab' && args.length === 1 && args[0] === '-l';
+}
+/** The primary invoke request is a declared query transport, not a mutation. */
+export async function executeInvokeQueryTransport(transportKind, writer) {
+    assertDeclaredNetworkTransport(transportKind);
+    return writer();
+}
+export async function executeSecondaryNetworkMutation(authority, transportKind, writer, projected) {
+    if (transportKind !== 'secondary-mutation')
+        throw new StrictReadOnlyError('readonly-physical-boundary-unsafe', 'boundary');
+    return authority.executeAsync({ phase: 'client-preflight', domain: 'external-effect', category: 'network-mutation', operation: 'send' }, writer, projected);
+}

package/packages/client/dist/errors/error-messages.js

@@ -1,2 +1,228 @@
-const t="support@neocortex.sh",u={AUTH_REFRESH_REQUIRED:{en:{summary:"Authentication must be refreshed.",whatHappened:"Credentials are configured, but a valid authentication token is unavailable. The token may have expired or the authentication service may be unreachable. Strict read-only commands do not refresh tokens.",whatToDo:"Check the server connection and retry. If authentication remains unavailable, re-activate outside strict read-only mode.",command:"neocortex activate YOUR-LICENSE-KEY",url:"https://neocortex.sh/portal"},"pt-BR":{summary:"A autentica\xE7\xE3o precisa ser renovada.",whatHappened:"As credenciais est\xE3o configuradas, mas n\xE3o h\xE1 um token de autentica\xE7\xE3o v\xE1lido dispon\xEDvel. O token pode ter expirado ou o servi\xE7o de autentica\xE7\xE3o pode estar inacess\xEDvel. Comandos estritamente somente leitura n\xE3o renovam tokens.",whatToDo:"Verifique a conex\xE3o com o servidor e tente novamente. Se a autentica\xE7\xE3o continuar indispon\xEDvel, reative fora do modo estritamente somente leitura.",command:"neocortex activate SUA-LICENSE-KEY",url:"https://neocortex.sh/portal"}},AUTH_EXPIRED:{en:{summary:"Your session has expired.",whatHappened:"The token we use to authenticate your CLI has expired. This is normal and happens every few hours.",whatToDo:"Re-activate with the license key that was emailed to you.",command:"neocortex activate YOUR-LICENSE-KEY",url:"https://neocortex.sh/portal"},"pt-BR":{summary:"Sua sess\xE3o expirou.",whatHappened:"O token de autentica\xE7\xE3o do CLI expirou. Isso \xE9 normal e acontece a cada poucas horas.",whatToDo:"Reative o CLI com a license key que voc\xEA recebeu por email.",command:"neocortex activate SUA-LICENSE-KEY",url:"https://neocortex.sh/portal"}},UPGRADE_REQUIRED:{en:{summary:"Your CLI version is outdated.",whatHappened:"The server requires a newer CLI version. Older versions are not allowed for security and compatibility reasons.",whatToDo:"Install the latest CLI globally with npm.",command:"npm install -g @ornexus/neocortex@latest"},"pt-BR":{summary:"Sua vers\xE3o do CLI est\xE1 desatualizada.",whatHappened:"O servidor exige uma vers\xE3o mais recente do CLI. Vers\xF5es antigas n\xE3o s\xE3o permitidas por motivos de seguran\xE7a e compatibilidade.",whatToDo:"Instale a vers\xE3o mais recente globalmente via npm.",command:"npm install -g @ornexus/neocortex@latest"}},RATE_LIMITED:{en:{summary:"You sent too many requests in a short window.",whatHappened:"You hit the rate limit for your plan. This protects the service from abuse and keeps it fast for everyone.",whatToDo:"Wait a few seconds and try again. If you hit this often, upgrading your plan raises the limit.",url:"https://neocortex.sh/portal/plans"},"pt-BR":{summary:"Voc\xEA fez muitas requisi\xE7\xF5es em pouco tempo.",whatHappened:"O limite de taxa do seu plano foi atingido. Isso protege o servi\xE7o contra abuso e mant\xE9m a velocidade para todos.",whatToDo:"Espere alguns segundos e tente novamente. Se isso acontece com frequ\xEAncia, fazer upgrade do seu plano aumenta o limite.",url:"https://neocortex.sh/portal/plans"}},TRIGGER_NOT_ALLOWED:{en:{summary:"This command is not available on your current plan.",whatHappened:"You tried to use a trigger that requires a paid plan (Pro or Enterprise).",whatToDo:"See the full comparison and upgrade in the portal.",url:"https://neocortex.sh/portal/plans"},"pt-BR":{summary:"Este comando n\xE3o est\xE1 dispon\xEDvel no seu plano atual.",whatHappened:"Voc\xEA tentou usar um trigger que requer um plano pago (Pro ou Enterprise).",whatToDo:"Veja a compara\xE7\xE3o completa e fa\xE7a upgrade no portal.",url:"https://neocortex.sh/portal/plans"}},QUOTA_EXCEEDED:{en:{summary:"Daily quota reached.",whatHappened:"You have used all invocations allowed by your plan today. Quotas reset at midnight UTC.",whatToDo:"Wait for the daily reset, or upgrade your plan for a higher quota.",url:"https://neocortex.sh/portal/plans"},"pt-BR":{summary:"Quota di\xE1ria atingida.",whatHappened:"Voc\xEA usou todas as invoca\xE7\xF5es permitidas pelo seu plano hoje. As quotas s\xE3o resetadas \xE0 meia-noite UTC.",whatToDo:"Aguarde o reset di\xE1rio ou fa\xE7a upgrade do plano para uma quota maior.",url:"https://neocortex.sh/portal/plans"}},SERVER_ERROR:{en:{summary:"Server error.",whatHappened:"Something went wrong on our side. We have logged the error and will investigate.",whatToDo:`Try again in a minute. If the problem persists, please contact ${t} with the details.`},"pt-BR":{summary:"Erro do servidor.",whatHappened:"Algo deu errado no nosso lado. O erro foi registrado e vamos investigar.",whatToDo:`Tente novamente em um minuto. Se o problema persistir, entre em contato: ${t}.`}},ECONNREFUSED:{en:{summary:"Cannot reach the Neocortex server.",whatHappened:"We could not open a connection to the server. This is usually a network problem on your side.",whatToDo:"Check your internet connection, any VPN or corporate proxy, and try again."},"pt-BR":{summary:"N\xE3o foi poss\xEDvel alcan\xE7ar o servidor Neocortex.",whatHappened:"N\xE3o conseguimos abrir uma conex\xE3o com o servidor. Isso geralmente \xE9 um problema de rede do seu lado.",whatToDo:"Verifique sua conex\xE3o, qualquer VPN ou proxy corporativo, e tente novamente."}},MACHINE_LIMIT_EXCEEDED:{en:{summary:"Machine limit reached.",whatHappened:"Your plan allows a limited number of active machines, and this one would exceed it.",whatToDo:"Deactivate a machine you no longer use from the portal, then re-run activate here.",url:"https://neocortex.sh/portal/machines"},"pt-BR":{summary:"Limite de m\xE1quinas atingido.",whatHappened:"Seu plano permite um n\xFAmero limitado de m\xE1quinas ativas, e esta ultrapassaria o limite.",whatToDo:"Desative uma m\xE1quina que voc\xEA n\xE3o usa mais no portal e rode activate aqui de novo.",url:"https://neocortex.sh/portal/machines"}},NOT_CONFIGURED:{en:{summary:"Neocortex is not configured on this machine.",whatHappened:"No license key was found. You need to run `neocortex activate` once before using the CLI.",whatToDo:"Get a license key from the portal and activate.",command:"neocortex activate YOUR-LICENSE-KEY",url:"https://neocortex.sh/portal"},"pt-BR":{summary:"Neocortex n\xE3o est\xE1 configurado nesta m\xE1quina.",whatHappened:"Nenhuma license key encontrada. Voc\xEA precisa rodar `neocortex activate` uma vez antes de usar o CLI.",whatToDo:"Pegue uma license key no portal e ative.",command:"neocortex activate SUA-LICENSE-KEY",url:"https://neocortex.sh/portal"}}};function r(o=process.env){return(o.LC_ALL??o.LANG??"").toLowerCase().startsWith("pt")?"pt-BR":"en"}function p(o,a=r()){const e=u[o];return e?e[a]??e.en??null:null}function c(o,a=r()){const e=[];e.push(""),e.push(`[Neocortex] ${o.summary}`),e.push("");const n=a==="pt-BR"?"O que aconteceu":"What happened",s=a==="pt-BR"?"O que fazer":"What to do",i=a==="pt-BR"?`Precisa de ajuda? ${t}`:`Need help? ${t}`;return e.push(`${n}: ${o.whatHappened}`),e.push(`${s}: ${o.whatToDo}`),o.command&&(e.push(""),e.push(`    ${o.command}`)),o.url&&(e.push(""),e.push(`    ${o.url}`)),e.push(""),e.push(i),e.push(""),e.join(`
-`)}function m(o){if(!o||typeof o!="object")return null;const a=o;return typeof a.code=="string"&&(a.code==="ECONNREFUSED"||a.code==="ENOTFOUND"||a.code==="ETIMEDOUT"||a.code==="ECONNRESET")||typeof a.message=="string"&&(/connect/i.test(a.message)&&/refus/i.test(a.message)||/fetch failed/i.test(a.message))?"ECONNREFUSED":null}export{r as detectErrorLocale,c as formatHumanizedError,p as humanizeError,m as inferErrorCodeFromException};
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * Central, localized error message helpers for CLI output. Turns
+ * server error codes and low-level exceptions into friendly, actionable
+ * messages with "What happened" + "What to do" + support email.
+ *
+ * Story P76.06.
+ */
+const SUPPORT_EMAIL = 'support@neocortex.sh';
+/** Localized copy per error code. */
+const MESSAGES = {
+    AUTH_REFRESH_REQUIRED: {
+        en: {
+            summary: 'Authentication must be refreshed.',
+            whatHappened: 'Credentials are configured, but a valid authentication token is unavailable. The token may have expired or the authentication service may be unreachable. Strict read-only commands do not refresh tokens.',
+            whatToDo: 'Check the server connection and retry. If authentication remains unavailable, re-activate outside strict read-only mode.',
+            command: 'neocortex activate YOUR-LICENSE-KEY',
+            url: 'https://neocortex.sh/portal',
+        },
+        'pt-BR': {
+            summary: 'A autenticação precisa ser renovada.',
+            whatHappened: 'As credenciais estão configuradas, mas não há um token de autenticação válido disponível. O token pode ter expirado ou o serviço de autenticação pode estar inacessível. Comandos estritamente somente leitura não renovam tokens.',
+            whatToDo: 'Verifique a conexão com o servidor e tente novamente. Se a autenticação continuar indisponível, reative fora do modo estritamente somente leitura.',
+            command: 'neocortex activate SUA-LICENSE-KEY',
+            url: 'https://neocortex.sh/portal',
+        },
+    },
+    AUTH_EXPIRED: {
+        en: {
+            summary: 'Your session has expired.',
+            whatHappened: 'The token we use to authenticate your CLI has expired. This is normal and happens every few hours.',
+            whatToDo: 'Re-activate with the license key that was emailed to you.',
+            command: 'neocortex activate YOUR-LICENSE-KEY',
+            url: 'https://neocortex.sh/portal',
+        },
+        'pt-BR': {
+            summary: 'Sua sessão expirou.',
+            whatHappened: 'O token de autenticação do CLI expirou. Isso é normal e acontece a cada poucas horas.',
+            whatToDo: 'Reative o CLI com a license key que você recebeu por email.',
+            command: 'neocortex activate SUA-LICENSE-KEY',
+            url: 'https://neocortex.sh/portal',
+        },
+    },
+    UPGRADE_REQUIRED: {
+        en: {
+            summary: 'Your CLI version is outdated.',
+            whatHappened: 'The server requires a newer CLI version. Older versions are not allowed for security and compatibility reasons.',
+            whatToDo: 'Install the latest CLI globally with npm.',
+            command: 'npm install -g @ornexus/neocortex@latest',
+        },
+        'pt-BR': {
+            summary: 'Sua versão do CLI está desatualizada.',
+            whatHappened: 'O servidor exige uma versão mais recente do CLI. Versões antigas não são permitidas por motivos de segurança e compatibilidade.',
+            whatToDo: 'Instale a versão mais recente globalmente via npm.',
+            command: 'npm install -g @ornexus/neocortex@latest',
+        },
+    },
+    RATE_LIMITED: {
+        en: {
+            summary: 'You sent too many requests in a short window.',
+            whatHappened: 'You hit the rate limit for your plan. This protects the service from abuse and keeps it fast for everyone.',
+            whatToDo: 'Wait a few seconds and try again. If you hit this often, upgrading your plan raises the limit.',
+            url: 'https://neocortex.sh/portal/plans',
+        },
+        'pt-BR': {
+            summary: 'Você fez muitas requisições em pouco tempo.',
+            whatHappened: 'O limite de taxa do seu plano foi atingido. Isso protege o serviço contra abuso e mantém a velocidade para todos.',
+            whatToDo: 'Espere alguns segundos e tente novamente. Se isso acontece com frequência, fazer upgrade do seu plano aumenta o limite.',
+            url: 'https://neocortex.sh/portal/plans',
+        },
+    },
+    TRIGGER_NOT_ALLOWED: {
+        en: {
+            summary: 'This command is not available on your current plan.',
+            whatHappened: 'You tried to use a trigger that requires a paid plan (Pro or Enterprise).',
+            whatToDo: 'See the full comparison and upgrade in the portal.',
+            url: 'https://neocortex.sh/portal/plans',
+        },
+        'pt-BR': {
+            summary: 'Este comando não está disponível no seu plano atual.',
+            whatHappened: 'Você tentou usar um trigger que requer um plano pago (Pro ou Enterprise).',
+            whatToDo: 'Veja a comparação completa e faça upgrade no portal.',
+            url: 'https://neocortex.sh/portal/plans',
+        },
+    },
+    QUOTA_EXCEEDED: {
+        en: {
+            summary: 'Daily quota reached.',
+            whatHappened: 'You have used all invocations allowed by your plan today. Quotas reset at midnight UTC.',
+            whatToDo: 'Wait for the daily reset, or upgrade your plan for a higher quota.',
+            url: 'https://neocortex.sh/portal/plans',
+        },
+        'pt-BR': {
+            summary: 'Quota diária atingida.',
+            whatHappened: 'Você usou todas as invocações permitidas pelo seu plano hoje. As quotas são resetadas à meia-noite UTC.',
+            whatToDo: 'Aguarde o reset diário ou faça upgrade do plano para uma quota maior.',
+            url: 'https://neocortex.sh/portal/plans',
+        },
+    },
+    SERVER_ERROR: {
+        en: {
+            summary: 'Server error.',
+            whatHappened: 'Something went wrong on our side. We have logged the error and will investigate.',
+            whatToDo: `Try again in a minute. If the problem persists, please contact ${SUPPORT_EMAIL} with the details.`,
+        },
+        'pt-BR': {
+            summary: 'Erro do servidor.',
+            whatHappened: 'Algo deu errado no nosso lado. O erro foi registrado e vamos investigar.',
+            whatToDo: `Tente novamente em um minuto. Se o problema persistir, entre em contato: ${SUPPORT_EMAIL}.`,
+        },
+    },
+    ECONNREFUSED: {
+        en: {
+            summary: 'Cannot reach the Neocortex server.',
+            whatHappened: 'We could not open a connection to the server. This is usually a network problem on your side.',
+            whatToDo: 'Check your internet connection, any VPN or corporate proxy, and try again.',
+        },
+        'pt-BR': {
+            summary: 'Não foi possível alcançar o servidor Neocortex.',
+            whatHappened: 'Não conseguimos abrir uma conexão com o servidor. Isso geralmente é um problema de rede do seu lado.',
+            whatToDo: 'Verifique sua conexão, qualquer VPN ou proxy corporativo, e tente novamente.',
+        },
+    },
+    MACHINE_LIMIT_EXCEEDED: {
+        en: {
+            summary: 'Machine limit reached.',
+            whatHappened: 'Your plan allows a limited number of active machines, and this one would exceed it.',
+            whatToDo: 'Deactivate a machine you no longer use from the portal, then re-run activate here.',
+            url: 'https://neocortex.sh/portal/machines',
+        },
+        'pt-BR': {
+            summary: 'Limite de máquinas atingido.',
+            whatHappened: 'Seu plano permite um número limitado de máquinas ativas, e esta ultrapassaria o limite.',
+            whatToDo: 'Desative uma máquina que você não usa mais no portal e rode activate aqui de novo.',
+            url: 'https://neocortex.sh/portal/machines',
+        },
+    },
+    NOT_CONFIGURED: {
+        en: {
+            summary: 'Neocortex is not configured on this machine.',
+            whatHappened: 'No license key was found. You need to run `neocortex activate` once before using the CLI.',
+            whatToDo: 'Get a license key from the portal and activate.',
+            command: 'neocortex activate YOUR-LICENSE-KEY',
+            url: 'https://neocortex.sh/portal',
+        },
+        'pt-BR': {
+            summary: 'Neocortex não está configurado nesta máquina.',
+            whatHappened: 'Nenhuma license key encontrada. Você precisa rodar `neocortex activate` uma vez antes de usar o CLI.',
+            whatToDo: 'Pegue uma license key no portal e ative.',
+            command: 'neocortex activate SUA-LICENSE-KEY',
+            url: 'https://neocortex.sh/portal',
+        },
+    },
+};
+/** Detect the best locale from LC_ALL / LANG. Falls back to 'en'. */
+export function detectErrorLocale(env = process.env) {
+    const raw = (env.LC_ALL ?? env.LANG ?? '').toLowerCase();
+    if (raw.startsWith('pt'))
+        return 'pt-BR';
+    return 'en';
+}
+/**
+ * Look up a humanized message for an error code.
+ * Returns null if the code is unknown -- caller should fall back to the
+ * raw server message.
+ */
+export function humanizeError(code, locale = detectErrorLocale()) {
+    const group = MESSAGES[code];
+    if (!group)
+        return null;
+    return group[locale] ?? group.en ?? null;
+}
+/**
+ * Format a humanized error for stderr. Always ends with the support email.
+ */
+export function formatHumanizedError(humanized, locale = detectErrorLocale()) {
+    const lines = [];
+    lines.push('');
+    lines.push(`[Neocortex] ${humanized.summary}`);
+    lines.push('');
+    const whatHappenedLabel = locale === 'pt-BR' ? 'O que aconteceu' : 'What happened';
+    const whatToDoLabel = locale === 'pt-BR' ? 'O que fazer' : 'What to do';
+    const needHelpLabel = locale === 'pt-BR'
+        ? `Precisa de ajuda? ${SUPPORT_EMAIL}`
+        : `Need help? ${SUPPORT_EMAIL}`;
+    lines.push(`${whatHappenedLabel}: ${humanized.whatHappened}`);
+    lines.push(`${whatToDoLabel}: ${humanized.whatToDo}`);
+    if (humanized.command) {
+        lines.push('');
+        lines.push(`    ${humanized.command}`);
+    }
+    if (humanized.url) {
+        lines.push('');
+        lines.push(`    ${humanized.url}`);
+    }
+    lines.push('');
+    lines.push(needHelpLabel);
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Infer an error code from a low-level error object (e.g., Node.js error
+ * thrown by fetch / dns / pg). Returns null if we cannot classify it.
+ */
+export function inferErrorCodeFromException(err) {
+    if (!err || typeof err !== 'object')
+        return null;
+    const e = err;
+    if (typeof e.code === 'string') {
+        if (e.code === 'ECONNREFUSED')
+            return 'ECONNREFUSED';
+        if (e.code === 'ENOTFOUND')
+            return 'ECONNREFUSED';
+        if (e.code === 'ETIMEDOUT')
+            return 'ECONNREFUSED';
+        if (e.code === 'ECONNRESET')
+            return 'ECONNREFUSED';
+    }
+    if (typeof e.message === 'string') {
+        if (/connect/i.test(e.message) && /refus/i.test(e.message))
+            return 'ECONNREFUSED';
+        if (/fetch failed/i.test(e.message))
+            return 'ECONNREFUSED';
+    }
+    return null;
+}

package/packages/client/dist/errors/frontmatter-diagnostics.js

@@ -1 +1,125 @@
-const l=["payload-selection","target-normalization","metadata-frontmatter"],d=["payload-selection-ambiguous","payload-selection-unavailable","markdown-link-target-malformed","markdown-link-target-ambiguous","markdown-link-target-external","markdown-link-target-unsafe-path","raw-target-malformed","raw-target-external","raw-target-unsafe-path","frontmatter-malformed","frontmatter-oversized","frontmatter-unsupported-value","frontmatter-explicit-selection-required"],t="*yoloop @docs/epics/epic-P204.md",a="docs/epics/epic-P204.md",n=Object.freeze({"payload-selection-ambiguous":Object.freeze({category:"payload-selection",summary:"The explicit Neocortex command could not be selected unambiguously.",remediation:"Pass exactly one explicit trigger and its project-local arguments; keep host wrapper metadata outside the selected payload."}),"payload-selection-unavailable":Object.freeze({category:"payload-selection",summary:"The explicit Neocortex command could not be selected safely.",remediation:"Retry with one explicit trigger. Do not include wrapper frontmatter, conversation history or delegated prompt text."}),"markdown-link-target-malformed":Object.freeze({category:"target-normalization",summary:"The Markdown target is malformed or is not a supported Markdown path.",remediation:"Use one complete Markdown link to a project-relative .md file or a trailing-slash directory.",example:t}),"markdown-link-target-ambiguous":Object.freeze({category:"target-normalization",summary:"More than one target or mixed target syntax was supplied.",remediation:"Pass exactly one raw path or one Markdown link target.",example:t}),"markdown-link-target-external":Object.freeze({category:"target-normalization",summary:"External Markdown targets are not supported.",remediation:"Reference a file already inside the project with a project-relative path.",example:t}),"markdown-link-target-unsafe-path":Object.freeze({category:"target-normalization",summary:"The Markdown target is outside the supported project-relative path boundary.",remediation:"Remove absolute, home, drive, backslash or traversal segments and use a project-relative path.",example:t}),"raw-target-malformed":Object.freeze({category:"target-normalization",summary:"The raw target is not a supported Markdown path.",remediation:"Use one project-relative .md file or a trailing-slash directory.",example:t}),"raw-target-external":Object.freeze({category:"target-normalization",summary:"External raw targets are not supported.",remediation:"Reference a file already inside the project with a project-relative path.",example:t}),"raw-target-unsafe-path":Object.freeze({category:"target-normalization",summary:"The raw target is outside the supported project-relative path boundary.",remediation:"Remove absolute, home, drive, backslash or traversal segments and use a project-relative path.",example:t}),"frontmatter-malformed":Object.freeze({category:"metadata-frontmatter",summary:"The leading YAML frontmatter envelope is malformed.",remediation:"Repair the bounded leading --- envelope and keep generated metadata fields scalar or string-list values.",example:a}),"frontmatter-oversized":Object.freeze({category:"metadata-frontmatter",summary:"The leading YAML frontmatter exceeds the public parsing limits.",remediation:"Reduce the metadata header and keep descriptive content in the Markdown body.",example:a}),"frontmatter-unsupported-value":Object.freeze({category:"metadata-frontmatter",summary:"A frontmatter field uses an unsupported value shape.",remediation:"Use allowlisted scalar fields and bounded string lists only.",example:a}),"frontmatter-explicit-selection-required":Object.freeze({category:"metadata-frontmatter",summary:"Target metadata cannot be projected before explicit file selection.",remediation:"Select one project-relative epic or story target before metadata discovery.",example:a})}),i=Object.freeze({category:"metadata-frontmatter",reasonCode:"frontmatter-diagnostic-unclassified",summary:"The frontmatter operation could not be classified safely.",remediation:"Retry with one explicit project-relative target and a bounded YAML header.",example:a});function m(r){const e=n[r];return e?Object.freeze({reasonCode:r,...e}):i}function s(r){const e=m(r),o=e.example?` Example: ${e.example}.`:"";return`${e.reasonCode} [${e.category}]: ${e.summary} Remediation: ${e.remediation}${o}`}export{l as FRONTMATTER_DIAGNOSTIC_CATEGORIES,d as FRONTMATTER_DIAGNOSTIC_REASON_CODES,s as formatFrontmatterDiagnostic,m as getFrontmatterDiagnostic};
+/**
+ * Public-safe diagnostics for the P204 frontmatter boundary.
+ *
+ * Diagnostic construction intentionally accepts a reason code only. Rejected
+ * source text, wrapper bodies, argv and filesystem paths are never inputs, so
+ * callers cannot accidentally reflect private content into logs.
+ */
+export const FRONTMATTER_DIAGNOSTIC_CATEGORIES = [
+    'payload-selection',
+    'target-normalization',
+    'metadata-frontmatter',
+];
+export const FRONTMATTER_DIAGNOSTIC_REASON_CODES = [
+    'payload-selection-ambiguous',
+    'payload-selection-unavailable',
+    'markdown-link-target-malformed',
+    'markdown-link-target-ambiguous',
+    'markdown-link-target-external',
+    'markdown-link-target-unsafe-path',
+    'raw-target-malformed',
+    'raw-target-external',
+    'raw-target-unsafe-path',
+    'frontmatter-malformed',
+    'frontmatter-oversized',
+    'frontmatter-unsupported-value',
+    'frontmatter-explicit-selection-required',
+];
+const TARGET_EXAMPLE = '*yoloop @docs/epics/epic-P204.md';
+const FRONTMATTER_EXAMPLE = 'docs/epics/epic-P204.md';
+const DIAGNOSTICS = Object.freeze({
+    'payload-selection-ambiguous': Object.freeze({
+        category: 'payload-selection',
+        summary: 'The explicit Neocortex command could not be selected unambiguously.',
+        remediation: 'Pass exactly one explicit trigger and its project-local arguments; keep host wrapper metadata outside the selected payload.',
+    }),
+    'payload-selection-unavailable': Object.freeze({
+        category: 'payload-selection',
+        summary: 'The explicit Neocortex command could not be selected safely.',
+        remediation: 'Retry with one explicit trigger. Do not include wrapper frontmatter, conversation history or delegated prompt text.',
+    }),
+    'markdown-link-target-malformed': Object.freeze({
+        category: 'target-normalization',
+        summary: 'The Markdown target is malformed or is not a supported Markdown path.',
+        remediation: 'Use one complete Markdown link to a project-relative .md file or a trailing-slash directory.',
+        example: TARGET_EXAMPLE,
+    }),
+    'markdown-link-target-ambiguous': Object.freeze({
+        category: 'target-normalization',
+        summary: 'More than one target or mixed target syntax was supplied.',
+        remediation: 'Pass exactly one raw path or one Markdown link target.',
+        example: TARGET_EXAMPLE,
+    }),
+    'markdown-link-target-external': Object.freeze({
+        category: 'target-normalization',
+        summary: 'External Markdown targets are not supported.',
+        remediation: 'Reference a file already inside the project with a project-relative path.',
+        example: TARGET_EXAMPLE,
+    }),
+    'markdown-link-target-unsafe-path': Object.freeze({
+        category: 'target-normalization',
+        summary: 'The Markdown target is outside the supported project-relative path boundary.',
+        remediation: 'Remove absolute, home, drive, backslash or traversal segments and use a project-relative path.',
+        example: TARGET_EXAMPLE,
+    }),
+    'raw-target-malformed': Object.freeze({
+        category: 'target-normalization',
+        summary: 'The raw target is not a supported Markdown path.',
+        remediation: 'Use one project-relative .md file or a trailing-slash directory.',
+        example: TARGET_EXAMPLE,
+    }),
+    'raw-target-external': Object.freeze({
+        category: 'target-normalization',
+        summary: 'External raw targets are not supported.',
+        remediation: 'Reference a file already inside the project with a project-relative path.',
+        example: TARGET_EXAMPLE,
+    }),
+    'raw-target-unsafe-path': Object.freeze({
+        category: 'target-normalization',
+        summary: 'The raw target is outside the supported project-relative path boundary.',
+        remediation: 'Remove absolute, home, drive, backslash or traversal segments and use a project-relative path.',
+        example: TARGET_EXAMPLE,
+    }),
+    'frontmatter-malformed': Object.freeze({
+        category: 'metadata-frontmatter',
+        summary: 'The leading YAML frontmatter envelope is malformed.',
+        remediation: 'Repair the bounded leading --- envelope and keep generated metadata fields scalar or string-list values.',
+        example: FRONTMATTER_EXAMPLE,
+    }),
+    'frontmatter-oversized': Object.freeze({
+        category: 'metadata-frontmatter',
+        summary: 'The leading YAML frontmatter exceeds the public parsing limits.',
+        remediation: 'Reduce the metadata header and keep descriptive content in the Markdown body.',
+        example: FRONTMATTER_EXAMPLE,
+    }),
+    'frontmatter-unsupported-value': Object.freeze({
+        category: 'metadata-frontmatter',
+        summary: 'A frontmatter field uses an unsupported value shape.',
+        remediation: 'Use allowlisted scalar fields and bounded string lists only.',
+        example: FRONTMATTER_EXAMPLE,
+    }),
+    'frontmatter-explicit-selection-required': Object.freeze({
+        category: 'metadata-frontmatter',
+        summary: 'Target metadata cannot be projected before explicit file selection.',
+        remediation: 'Select one project-relative epic or story target before metadata discovery.',
+        example: FRONTMATTER_EXAMPLE,
+    }),
+});
+const UNKNOWN_DIAGNOSTIC = Object.freeze({
+    category: 'metadata-frontmatter',
+    reasonCode: 'frontmatter-diagnostic-unclassified',
+    summary: 'The frontmatter operation could not be classified safely.',
+    remediation: 'Retry with one explicit project-relative target and a bounded YAML header.',
+    example: FRONTMATTER_EXAMPLE,
+});
+export function getFrontmatterDiagnostic(reasonCode) {
+    const definition = DIAGNOSTICS[reasonCode];
+    if (!definition)
+        return UNKNOWN_DIAGNOSTIC;
+    return Object.freeze({ reasonCode: reasonCode, ...definition });
+}
+export function formatFrontmatterDiagnostic(reasonCode) {
+    const diagnostic = getFrontmatterDiagnostic(reasonCode);
+    const example = diagnostic.example ? ` Example: ${diagnostic.example}.` : '';
+    return `${diagnostic.reasonCode} [${diagnostic.category}]: ${diagnostic.summary} Remediation: ${diagnostic.remediation}${example}`;
+}