shakers-cli-beta 0.8.0-beta.0

package/src/share-payload.js

@@ -0,0 +1,300 @@
+'use strict';
+
+// The derived-payload whitelist for the `usage/reports` ingest, extracted from src/share.js (structure refactor, issue 020).
+
+const { scrubSecrets } = require('./agent-synthesis');
+const { MAX_DEFINITION_CHARS } = require('./agent-evaluation');
+
+// Only these fields leave the machine.
+function whitelistSchedulerProbe(probe) {
+  return {
+    inspected: !!(probe && probe.inspected),
+    matches: probe && typeof probe.matches === 'number' ? probe.matches : 0,
+  };
+}
+
+// WHY ONE MORE FIELD IS ADMISSIBLE ON THE AGENT WHITELIST (issue 115).
+function agentCatalogIdsByName(report) {
+  const evaluations =
+    report.agentEvaluation && Array.isArray(report.agentEvaluation.evaluations)
+      ? report.agentEvaluation.evaluations
+      : [];
+
+  const byName = new Map();
+  for (const e of evaluations) {
+    if (!e || typeof e.name !== 'string' || !e.name) continue;
+    if (byName.has(e.name)) continue; // first occurrence wins — see docblock
+    const id =
+      e.classification && typeof e.classification.catalogId === 'string' && e.classification.catalogId
+        ? e.classification.catalogId
+        : null;
+    byName.set(e.name, id);
+  }
+  return byName;
+}
+
+// WHY THE AGENT `definition` NOW RIDES THE INGEST PAYLOAD (agent-classifier fix).
+function agentDefinitionsByName(report) {
+  const definitions = Array.isArray(report.agentDefinitions)
+    ? report.agentDefinitions
+    : [];
+  const byName = new Map();
+  for (const entry of definitions) {
+    if (!entry || typeof entry.name !== 'string' || !entry.name) continue;
+    if (byName.has(entry.name)) continue; // first occurrence wins — mirrors agentCatalogIdsByName
+    const text = typeof entry.definition === 'string' ? entry.definition : '';
+    byName.set(entry.name, scrubSecrets(text).slice(0, MAX_DEFINITION_CHARS));
+  }
+  return byName;
+}
+
+function derivePayload(report, maturity) {
+  const agents = Array.isArray(report.agents) ? report.agents : [];
+  const catalogIdsByName = agentCatalogIdsByName(report);
+  const definitionsByName = agentDefinitionsByName(report);
+  const technologies = Array.isArray(report.technologies) ? report.technologies : [];
+  const synthesisAgents =
+    report.agentSynthesis && Array.isArray(report.agentSynthesis.agents)
+      ? report.agentSynthesis.agents
+      : [];
+
+  const mcp = report.mcp || {};
+  const memory = report.memory || {};
+  const automations = report.automations || {};
+  const automationsScripts = automations.scripts || {};
+  const automationsSchedulers = automations.schedulers || {};
+  const browserTools = report.browserTools || {};
+  const browserToolsVia = browserTools.via || {};
+
+  return {
+    schemaVersion: report.schemaVersion,
+    generatedAt: report.generatedAt,
+    anonId: report.anonId,
+    platform: report.platform,
+    level: maturity.level,
+    levelName: maturity.name,
+    score: maturity.score,
+    totalDetected: report.summary.totalDetected,
+    categories: report.summary.categories,
+    tools: report.tools.map((t) => ({
+      id: t.id,
+      detected: t.detected,
+      depth: t.depth || {},
+    })),
+    agents: agents.map((a) => ({
+      name: a.name,
+      tools: Array.isArray(a.tools) ? a.tools : [],
+      model: a.model || null,
+      parent: a.parent || null,
+      // issue 115 — the ONLY classification field that travels.
+      catalogId: catalogIdsByName.get(a.name) || null,
+      // agent-classifier fix — the agent's own definition (frontmatter description + body), scrubbed + capped.
+      ...(definitionsByName.get(a.name)
+        ? { definition: definitionsByName.get(a.name) }
+        : {}),
+    })),
+    agentCounts: report.agentCounts || { agents: 0, skills: 0, commands: 0, mcpServers: 0, hooks: 0 },
+    technologies,
+    agentSynthesis: synthesisAgents.map((a) => ({
+      name: a.name,
+      symbolicName: scrubSecrets(a.symbolicName || '') || null,
+      whatItDoes: scrubSecrets(a.whatItDoes || '') || null,
+    })),
+    tier: typeof maturity.tier === 'number' ? maturity.tier : null,
+    tierKey: maturity.tierKey || null,
+    mcp: {
+      countsByCategory: { ...(mcp.countsByCategory || { data: 0, comms: 0, dev: 0, browser: 0, other: 0 }) },
+      total: typeof mcp.total === 'number' ? mcp.total : 0,
+    },
+    memory: {
+      totalImports: typeof memory.totalImports === 'number' ? memory.totalImports : 0,
+      maxDepth: typeof memory.maxDepth === 'number' ? memory.maxDepth : 0,
+      layered: !!memory.layered,
+    },
+    automations: {
+      scripts: {
+        npm: typeof automationsScripts.npm === 'number' ? automationsScripts.npm : 0,
+        shell: typeof automationsScripts.shell === 'number' ? automationsScripts.shell : 0,
+      },
+      jsonPiping: typeof automations.jsonPiping === 'number' ? automations.jsonPiping : 0,
+      schedulers: {
+        cron: whitelistSchedulerProbe(automationsSchedulers.cron),
+        launchd: whitelistSchedulerProbe(automationsSchedulers.launchd),
+        pm2: whitelistSchedulerProbe(automationsSchedulers.pm2),
+        systemd: whitelistSchedulerProbe(automationsSchedulers.systemd),
+      },
+    },
+    browserTools: {
+      detected: !!browserTools.detected,
+      count: typeof browserTools.count === 'number' ? browserTools.count : 0,
+      via: {
+        dependency: Array.isArray(browserToolsVia.dependencies) && browserToolsVia.dependencies.length > 0,
+        mcp: Array.isArray(browserToolsVia.mcp) && browserToolsVia.mcp.length > 0,
+      },
+    },
+    // Hybrid evaluation, Slice 1: two DETERMINISTIC behavioural blocks (no LLM).
+    gitActivity: whitelistGitActivity(report.gitActivity),
+    sessions: whitelistSessions(report.sessions),
+    // Hybrid evaluation, Slice 2: one DETERMINISTIC block (workStreams) and two REDACTED-excerpt blocks (steering, decisions).
+    workStreams: whitelistWorkStreams(report.workStreams),
+    steering: whitelistSteering(report.steering),
+    decisions: whitelistDecisions(report.decisions),
+    // Hybrid evaluation, Slice 3c: PER-CANDIDATE authorship + depth (per detected skill, per detected agent).
+    detectionEvidence: whitelistDetectionEvidence(report.detectionEvidence),
+  };
+}
+
+// Re-derives the `detectionEvidence` block field-by-field (never spreads the source).
+function whitelistDetectionEvidence(evidence) {
+  if (!evidence || typeof evidence !== 'object') return null;
+  const skills = Array.isArray(evidence.skills)
+    ? evidence.skills.map((s) => ({
+        tech: typeof s.tech === 'string' ? s.tech : '',
+        authoredFileCount: numOr0(s.authoredFileCount),
+        totalFileCount: numOr0(s.totalFileCount),
+        authorshipKnown: !!s.authorshipKnown,
+        depth: numOrNull(s.depth),
+        vendored: !!s.vendored,
+        recencyDays: numOrNull(s.recencyDays),
+      }))
+    : [];
+  const agents = Array.isArray(evidence.agents)
+    ? evidence.agents.map((a) => ({
+        name: typeof a.name === 'string' ? a.name : '',
+        tools: Array.isArray(a.tools)
+          ? a.tools.filter((t) => typeof t === 'string')
+          : [],
+        model: typeof a.model === 'string' && a.model ? a.model : null,
+        authoredFileCount: numOr0(a.authoredFileCount),
+        totalFileCount: numOr0(a.totalFileCount),
+        authorshipKnown: !!a.authorshipKnown,
+        depth: numOrNull(a.depth),
+        vendored: !!a.vendored,
+        recencyDays: numOrNull(a.recencyDays),
+      }))
+    : [];
+  return { skills, agents, provenance: whitelistProvenance(evidence.provenance) };
+}
+
+// Re-derives the repo-level anti-noise `provenance` (Slice 3): the (weak) fork signal and the (conservative) boilerplate/tutorial signal.
+function whitelistProvenance(provenance) {
+  if (!provenance || typeof provenance !== 'object') return null;
+  const marker =
+    typeof provenance.boilerplateMarker === 'string' && provenance.boilerplateMarker
+      ? provenance.boilerplateMarker.slice(0, 60)
+      : null;
+  const forkSignal =
+    typeof provenance.forkSignal === 'string' && provenance.forkSignal
+      ? provenance.forkSignal.slice(0, 60)
+      : null;
+  return {
+    fork: !!provenance.fork,
+    forkSignal,
+    boilerplate: !!provenance.boilerplate,
+    boilerplateMarker: marker,
+  };
+}
+
+function numOrNull(n) {
+  return typeof n === 'number' && Number.isFinite(n) ? n : null;
+}
+
+// Re-derives the `workStreams` block field-by-field (never spreads the source).
+// `null` when absent — the server treats it as "not reported".
+function whitelistWorkStreams(ws) {
+  if (!ws || typeof ws !== 'object') return null;
+  return {
+    streamCount: numOr0(ws.streamCount),
+    multiDayStreams: numOr0(ws.multiDayStreams),
+    avgCommitsPerSession: numOr0(ws.avgCommitsPerSession),
+    maxStreamSpanDays: numOr0(ws.maxStreamSpanDays),
+  };
+}
+
+// Re-derives the `steering` block.
+function whitelistSteering(s) {
+  if (!s || typeof s !== 'object') return null;
+  return {
+    steeringTraceCount: numOr0(s.steeringTraceCount),
+    redactedSteeringExcerpts: whitelistExcerpts(s.redactedSteeringExcerpts),
+  };
+}
+
+// Re-derives the `decisions` block, same discipline as `steering`. `null` when absent.
+function whitelistDecisions(d) {
+  if (!d || typeof d !== 'object') return null;
+  return {
+    decisionExchangeCount: numOr0(d.decisionExchangeCount),
+    redactedDecisionExcerpts: whitelistExcerpts(d.redactedDecisionExcerpts),
+  };
+}
+
+const MAX_WHITELISTED_EXCERPTS = 20;
+const MAX_WHITELISTED_EXCERPT_LEN = 200;
+function whitelistExcerpts(arr) {
+  return Array.isArray(arr)
+    ? arr
+        .filter((x) => typeof x === 'string' && x)
+        .slice(0, MAX_WHITELISTED_EXCERPTS)
+        .map((x) => scrubSecrets(x).slice(0, MAX_WHITELISTED_EXCERPT_LEN))
+        .filter((x) => x)
+    : [];
+}
+
+// Re-derives the `gitActivity` block field-by-field (never spreads the source).
+// `null` when absent — the server treats it as "not reported".
+function whitelistGitActivity(git) {
+  if (!git || typeof git !== 'object') return null;
+  const filesByType = {};
+  if (git.filesByType && typeof git.filesByType === 'object') {
+    for (const [ext, count] of Object.entries(git.filesByType)) {
+      if (typeof count === 'number') filesByType[ext] = count;
+    }
+  }
+  return {
+    commitCount: numOr0(git.commitCount),
+    authoredCommitCount: numOr0(git.authoredCommitCount),
+    linesAdded: numOr0(git.linesAdded),
+    linesDeleted: numOr0(git.linesDeleted),
+    filesByType,
+    velocity: numOr0(git.velocity),
+    spanDays: numOr0(git.spanDays),
+  };
+}
+
+// Re-derives the `sessions` block field-by-field (never spreads the source).
+function whitelistSessions(sessions) {
+  if (!sessions || typeof sessions !== 'object') return null;
+  return {
+    toolsSeen: Array.isArray(sessions.toolsSeen)
+      ? sessions.toolsSeen.filter((t) => typeof t === 'string')
+      : [],
+    sessionCount: numOr0(sessions.sessionCount),
+    subagentRunCount: numOr0(sessions.subagentRunCount),
+    activeHours: numOrNull(sessions.activeHours),
+    crossToolLinks: numOr0(sessions.crossToolLinks),
+    filesTouchedCount: numOr0(sessions.filesTouchedCount),
+    bashCommandsCount: numOr0(sessions.bashCommandsCount),
+    planningSignalCount: numOr0(sessions.planningSignalCount),
+    // Recency-windowed traction signals for the hub profile.
+    sessions90d: numOrNull(sessions.sessions90d),
+    activeDaysPerWeek: numOrNull(sessions.activeDaysPerWeek),
+    blindApprovalCount: numOrNull(sessions.blindApprovalCount),
+    humanTurnCount: numOrNull(sessions.humanTurnCount),
+    specificInstructionCount: numOrNull(sessions.specificInstructionCount),
+    instructionTurnCount: numOrNull(sessions.instructionTurnCount),
+    avgInstructionLength: numOrNull(sessions.avgInstructionLength),
+    redactedCommandSample: Array.isArray(sessions.redactedCommandSample)
+      ? sessions.redactedCommandSample
+          .filter((c) => typeof c === 'string')
+          .map((c) => scrubSecrets(c).slice(0, MAX_WHITELISTED_EXCERPT_LEN))
+          .filter((c) => c)
+      : [],
+  };
+}
+
+function numOr0(n) {
+  return typeof n === 'number' && Number.isFinite(n) ? n : 0;
+}
+
+module.exports = { derivePayload };

package/src/share.js

@@ -0,0 +1,184 @@
+'use strict';
+
+const crypto = require('crypto');
+
+const { getIngestEndpoint, isTalentProfile } = require('./config');
+const { requestBackend } = require('./backend-request');
+const { recordBackendAcceptance } = require('./report-store');
+const {
+  consentPath,
+  SEND_THROTTLE_MS,
+  loadConsentState,
+  saveConsentState,
+  getConsentDecision,
+  hasTraceContentConsent,
+  isValidEmail,
+  normalizeEmail,
+  recordConsent,
+  getConsentStatus,
+  revokeConsent,
+  resetConsent,
+  clearConsentState,
+  setEmail,
+  isThrottled,
+} = require('./share-consent-state');
+const { derivePayload } = require('./share-payload');
+const {
+  deriveCertificationPayload,
+  isCertifyThrottled,
+  CERTIFY_SEND_THROTTLE_MS,
+} = require('./share-certification');
+
+// Sharing (= PERSISTENCE) layer — the thin transport + orchestration.
+
+/* ---------- minimal HTTP utility (no dependencies) ---------- */
+
+// POSTs `body` to the ONE backend (talents-ai-score, ADR-042 — the PRIMARY -> FALLBACK chain is retired), via src/backend-request.js.
+async function requestJsonBackend(endpoint, body, { timeoutMs = 15000, idempotencyKey = null } = {}) {
+  const { status, raw, backend } = await requestBackend({ endpoint, body, timeoutMs, idempotencyKey });
+  let json = null;
+  try { json = raw ? JSON.parse(raw) : null; } catch { /* non-JSON response */ }
+  return { status, json, raw, backend };
+}
+
+/* ---------- automatic sending ---------- */
+
+async function autoShare(report, maturity, { root, bypassThrottle = false } = {}) {
+  const state = loadConsentState();
+  const decision = getConsentDecision(state);
+
+  if (decision !== 'granted') {
+    return { ok: false, skipped: true, reason: decision === 'denied' ? 'consent-denied' : 'no-decision' };
+  }
+  if (!state.email) {
+    return { ok: false, skipped: true, reason: 'no-email' };
+  }
+  // ADR-006: never SEND under an email whose ownership wasn't proven.
+  if (state.emailVerified === false && isTalentProfile()) {
+    return { ok: false, skipped: true, reason: 'email-unverified' };
+  }
+  if (!bypassThrottle && isThrottled(state)) {
+    return { ok: false, skipped: true, reason: 'throttled' };
+  }
+
+  const endpoint = getIngestEndpoint();
+  if (!endpoint) {
+    return { ok: false, skipped: true, reason: 'no-endpoint-configured' };
+  }
+
+  const payload = derivePayload(report, maturity);
+
+  const idempotencyKey = crypto.randomUUID();
+  let res;
+  try {
+    res = await requestJsonBackend(endpoint, { email: state.email, payload }, { idempotencyKey });
+  } catch (e) {
+    // Network failure (on every hop): doesn't break the local report.
+    return { ok: false, skipped: false, reason: 'network-error', error: e.message };
+  }
+
+  if (res.status >= 200 && res.status < 300) {
+    state.lastSentAt = new Date().toISOString();
+    saveConsentState(state);
+    try {
+      recordBackendAcceptance({ root, kind: 'footprint', backend: res.backend });
+    } catch {
+      // Never break the send over a failed local state write.
+    }
+    return { ok: true, response: res.json, backend: res.backend };
+  }
+  if (res.status === 429) {
+    return { ok: false, skipped: false, reason: 'rate-limited' };
+  }
+  if (res.status === 503) {
+    // Generic "service unavailable" from the server (ADR-011 retires the
+    // server-side kill switch that used to be the main 503 cause).
+    return { ok: false, skipped: false, reason: 'service-unavailable' };
+  }
+  return { ok: false, skipped: false, reason: `http-${res.status}` };
+}
+
+/* ---------- certification persistence (skill-code-certification, issue 005) ---------- */
+
+// Persists the analyzed certification result if (and only if) consent is granted.
+async function shareCertification(items, { repository = null, commitRange = null, toolVersion = null, superadminToken = null, root = null } = {}) {
+  const state = loadConsentState();
+  const decision = getConsentDecision(state);
+
+  if (decision !== 'granted') {
+    return { ok: false, skipped: true, reason: decision === 'denied' ? 'consent-denied' : 'no-decision' };
+  }
+  if (!state.email) {
+    return { ok: false, skipped: true, reason: 'no-email' };
+  }
+  // ADR-006 (mirror of autoShare): don't persist under an unverified email.
+  if (state.emailVerified === false) {
+    return { ok: false, skipped: true, reason: 'email-unverified' };
+  }
+  if (isCertifyThrottled(state)) {
+    return { ok: false, skipped: true, reason: 'throttled' };
+  }
+
+  const payload = deriveCertificationPayload(items, { repository, commitRange, toolVersion });
+  if (payload.skillCodeAssessments.length === 0) {
+    return { ok: false, skipped: true, reason: 'nothing-to-persist' };
+  }
+
+  const endpoint = getIngestEndpoint();
+  if (!endpoint) {
+    return { ok: false, skipped: true, reason: 'no-endpoint-configured' };
+  }
+
+  let res;
+  try {
+    // ADR-027: forward the superadmin session token so the backend stamps test_origin=true (server-authoritative, non-prod only).
+    const body = { email: state.email, payload };
+    if (superadminToken) body.superadminToken = superadminToken;
+    // Idempotency-Key (three-way security review, cross-repo): ONE key per
+    // logical certification-persist submission — same reasoning as autoShare.
+    const idempotencyKey = crypto.randomUUID();
+    res = await requestJsonBackend(endpoint, body, { idempotencyKey });
+  } catch (e) {
+    return { ok: false, skipped: false, reason: 'network-error', error: e.message };
+  }
+
+  if (res.status >= 200 && res.status < 300) {
+    state.lastCertifySentAt = new Date().toISOString();
+    saveConsentState(state);
+    try {
+      recordBackendAcceptance({ root, kind: 'certification', backend: res.backend });
+    } catch {
+      // Never break the send over a failed local state write.
+    }
+    return { ok: true, response: res.json, backend: res.backend };
+  }
+  if (res.status === 429) {
+    return { ok: false, skipped: false, reason: 'rate-limited' };
+  }
+  return { ok: false, skipped: false, reason: `http-${res.status}` };
+}
+
+module.exports = {
+  autoShare,
+  deriveCertificationPayload,
+  shareCertification,
+  isCertifyThrottled,
+  CERTIFY_SEND_THROTTLE_MS,
+  loadConsentState,
+  saveConsentState,
+  getConsentDecision,
+  hasTraceContentConsent,
+  recordConsent,
+  getConsentStatus,
+  revokeConsent,
+  resetConsent,
+  clearConsentState,
+  setEmail,
+  isValidEmail,
+  normalizeEmail,
+  isThrottled,
+  derivePayload,
+  requestJsonBackend,
+  consentPath,
+  SEND_THROTTLE_MS,
+};

package/src/show-project-client.js

@@ -0,0 +1,58 @@
+'use strict';
+
+// Position detail client (hub `works/positions/:id/detail`, talent Bearer).
+// A "project" here is the Position + its parent project's fields.
+
+const { postJsonWithTimeout } = require('./backend-request');
+const { reasonForError } = require('./onboarding-client');
+
+const DEFAULT_TIMEOUT_MS = 20000;
+
+function parseJson(raw) {
+  try {
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+function bearerHeaders(accessToken) {
+  const headers = {};
+  if (typeof accessToken === 'string' && accessToken) headers.Authorization = `Bearer ${accessToken}`;
+  return headers;
+}
+
+async function requestPositionDetail({ hubAccessToken } = {}, { positionId, endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!positionId) return { ok: false, reason: 'no-id' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-hub-token' };
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, null, timeoutMs, 'GET', null, bearerHeaders(hubAccessToken));
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  if (res.status === 404) return { ok: false, reason: 'not-found' };
+  if (res.status < 200 || res.status >= 300) return { ok: false, reason: reasonForError(res.status, res.raw) };
+
+  const env = parseJson(res.raw);
+  const data = env && env.status === 'OK' ? env.data : env;
+  if (!data || typeof data !== 'object') return { ok: false, reason: 'bad-response' };
+  return { ok: true, position: data.position || null, redirectUrl: data.redirectUrl || null };
+}
+
+// CLI+MCP entry: resolve the endpoint from config, then fetch one detail.
+async function fetchPositionDetail(deps = {}, { hubAccessToken, positionId, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const {
+    getPositionDetailEndpoint = require('./config').getPositionDetailEndpoint,
+    requestPositionDetail: request = requestPositionDetail,
+  } = deps;
+  const endpoint = getPositionDetailEndpoint(positionId);
+  if (!endpoint) return { ok: false, reason: positionId ? 'no-endpoint' : 'no-id' };
+  return request({ hubAccessToken }, { positionId, endpoint, timeoutMs });
+}
+
+module.exports = {
+  requestPositionDetail,
+  fetchPositionDetail,
+};

package/src/show-project-flow.js

@@ -0,0 +1,119 @@
+'use strict';
+
+// `show-project` flow: render the detail of one Position/Project. Read-only.
+
+const { styleLabel, styleLabelPrefix } = require('./ansi');
+const { resolveName } = require('./translations-client');
+
+function makeShowProjectDeps(overrides = {}) {
+  const client = require('./show-project-client');
+  return {
+    fetchPositionDetail: (opts) => client.fetchPositionDetail({}, opts),
+    resolveRef: (raw) => require('./find-projects-cache').resolvePositionRef(raw),
+    fetchTranslationMap: (opts) => require('./translations-client').fetchTranslationMap({}, opts),
+    ...overrides,
+  };
+}
+
+// Skill names come as static-data i18n KEYS; resolve them to readable names
+// (only fetch the translations map when there is a key to resolve).
+async function resolvePositionSkills(position, { deps, hubAccessToken, lang }) {
+  const skills = position && Array.isArray(position.skills) ? position.skills : null;
+  if (!skills || !skills.some((s) => s && /^staticData/.test(s.name))) return position;
+  const tm = await deps.fetchTranslationMap({ hubAccessToken, lang });
+  const map = tm && tm.ok ? tm.map : null;
+  if (!map) return position;
+  return { ...position, skills: skills.map((s) => ({ ...s, name: resolveName(map, s && s.name) })) };
+}
+
+function budgetLine(budget, fp) {
+  if (!budget) return fp.budgetUnknown;
+  if (budget.display) return budget.display;
+  if (budget.from != null || budget.to != null) {
+    return `${budget.from ?? '·'}–${budget.to ?? '·'}${budget.unit ? ` ${budget.unit}` : ''}`;
+  }
+  return fp.budgetUnknown;
+}
+
+// The human render never prints the position/project ids (they stay in --json).
+function renderDetail(io, fp, p) {
+  const company = p.company && p.company.name ? p.company.name : (p.company && p.company.restricted ? fp.companyRestricted : null);
+  io.section(p.title || fp.untitled);
+  if (company) io.notify(styleLabelPrefix(fp.companyLine(company)));
+  if (p.subtitle) io.notify(styleLabelPrefix(fp.projectLine(p.subtitle)));
+
+  const meta = [
+    p.attendance || null,
+    p.country || null,
+    p.requiredMonthlyHours != null ? fp.hoursPerMonth(p.requiredMonthlyHours) : null,
+    budgetLine(p.budget, fp),
+    p.match != null ? fp.matchScore(p.match) : null,
+  ].filter(Boolean);
+  io.notify(meta.join(' · '));
+
+  const skills = Array.isArray(p.skills) ? p.skills.map((s) => s && s.name).filter(Boolean) : [];
+  if (skills.length) io.notify(styleLabelPrefix(fp.skillsLine(skills.join(', '))));
+  const langs = Array.isArray(p.languages) ? p.languages.filter(Boolean) : [];
+  if (langs.length) io.notify(styleLabelPrefix(fp.languagesLine(langs.join(', '))));
+
+  const flags = [
+    p.isSaved ? fp.savedBadge : null,
+    p.hasApplied ? fp.appliedBadge : (p.canApply ? fp.canApplyBadge : null),
+  ].filter(Boolean);
+  if (flags.length) io.notify(flags.join(' · '));
+
+  if (p.description) { io.section(fp.descriptionHeading); io.notify(p.description.trim()); }
+  if (p.goals) { io.section(fp.goalsHeading); io.notify(p.goals.trim()); }
+  const faqs = Array.isArray(p.faqs) ? p.faqs : [];
+  if (faqs.length) {
+    io.section(fp.faqsHeading);
+    faqs.forEach((f) => { if (f && f.question) io.notify(`${styleLabel(f.question)}${f.answer ? `\n  ${f.answer}` : ''}`); });
+  }
+}
+
+async function runShowProject({ io, rawOut, lang = 'en', session, catalog, opts = {}, deps = makeShowProjectDeps() }) {
+  const fp = catalog.showProject;
+  const hubAccessToken = session ? session.hubAccessToken : null;
+  // A pure integer resolves against the last `find-projects` listing; a UUID/Mongo id passes through.
+  const resolved = deps.resolveRef(opts.id);
+  if (!resolved.ok) {
+    io.error(resolved.reason === 'no-cache' ? fp.refNoCache
+      : resolved.reason === 'out-of-range' ? fp.refOutOfRange(resolved.count)
+        : fp.idRequired);
+    return { ok: false, reason: resolved.reason };
+  }
+  const positionId = resolved.id;
+
+  const doFetch = () => deps.fetchPositionDetail({ hubAccessToken, positionId });
+  const res = opts.json ? await doFetch() : await io.withProgress(fp.loading, doFetch);
+  if (!res.ok) {
+    io.error(res.reason === 'not-found' ? fp.notFound : fp.fetchFailed(res.reason));
+    return { ok: false, reason: res.reason };
+  }
+  if (!res.position) {
+    // --json must stay machine-readable even when the position is hidden.
+    if (opts.json) {
+      (rawOut || ((s) => process.stdout.write(s)))(`${JSON.stringify({ ok: true, position: null, redirectUrl: res.redirectUrl }, null, 2)}\n`);
+      return { ok: true, position: null, redirectUrl: res.redirectUrl };
+    }
+    io.notify(fp.notVisible);
+    return { ok: true, position: null, redirectUrl: res.redirectUrl };
+  }
+
+  const position = await resolvePositionSkills(res.position, { deps, hubAccessToken, lang });
+
+  if (opts.json) {
+    (rawOut || ((s) => process.stdout.write(s)))(`${JSON.stringify({ ok: true, position, redirectUrl: res.redirectUrl }, null, 2)}\n`);
+    return { ok: true, position };
+  }
+
+  renderDetail(io, fp, position);
+  io.success(fp.done);
+  return { ok: true, position };
+}
+
+module.exports = {
+  makeShowProjectDeps,
+  runShowProject,
+  renderDetail,
+};