@thebackstoryis/engineering-with-ai 0.2.9

package/public/team-hub/app.js

@@ -0,0 +1,202 @@
+const state = { portfolio: null, selectedId: null, resources: null, selectedResource: null };
+const tokenInput = document.querySelector('#hubToken');
+const message = document.querySelector('#message');
+const portfolioSection = document.querySelector('#portfolio');
+const projectList = document.querySelector('#projectList');
+const projectDetail = document.querySelector('#projectDetail');
+const summary = document.querySelector('#summary');
+const resourceRegistry = document.querySelector('#resourceRegistry');
+const resourceList = document.querySelector('#resourceList');
+const resourceDetail = document.querySelector('#resourceDetail');
+
+function el(name, className, text) {
+  const node = document.createElement(name);
+  if (className) node.className = className;
+  if (text !== undefined) node.textContent = String(text);
+  return node;
+}
+
+async function teamHubApi(path, token = sessionStorage.getItem('ewai.team-hub.token')) {
+  const response = await fetch(path, { headers: token ? { authorization: `Bearer ${token}` } : {} });
+  const body = await response.json().catch(() => null);
+  if (!response.ok) throw new Error(body?.error?.message ?? `Team Hub returned HTTP ${response.status}.`);
+  return body;
+}
+
+function evidenceRow(label, value) {
+  const row = el('div', 'evidence-row');
+  row.append(el('dt', '', label), el('dd', '', value ?? 'Not available'));
+  return row;
+}
+
+function renderSummary() {
+  summary.replaceChildren();
+  for (const [label, value] of Object.entries({ Projects: state.portfolio.summary.total, Current: state.portfolio.summary.current, Stale: state.portfolio.summary.stale, Attention: state.portfolio.summary.attention })) {
+    const card = el('div', 'summary-card');
+    card.append(el('span', 'summary-value', value), el('span', 'summary-label', label));
+    summary.append(card);
+  }
+}
+
+function renderDetail() {
+  const project = state.portfolio?.projects.find(({ id }) => id === state.selectedId);
+  projectDetail.replaceChildren();
+  if (!project) {
+    projectDetail.append(el('p', 'empty-state', 'Choose a connected project.'));
+    return;
+  }
+  const heading = el('header', 'detail-heading');
+  const title = el('div');
+  title.append(el('p', 'eyebrow', 'SELECTED PROJECT'), el('h3', '', project.name));
+  heading.append(title, el('span', `freshness freshness-${project.freshness.state}`, project.freshness.state));
+  const evidence = el('dl', 'evidence-grid');
+  evidence.append(
+    evidenceRow('Last accepted', project.evidence.acceptedAt),
+    evidenceRow('Submitted', project.evidence.submittedAt),
+    evidenceRow('Receipt', project.evidence.receiptId),
+    evidenceRow('Snapshot digest', project.evidence.snapshotDigest),
+    evidenceRow('EWAI', project.ewaiVersion),
+    evidenceRow('Revision digest', project.revisionDigest),
+  );
+  const delivery = el('section', 'detail-section');
+  delivery.append(el('h4', '', 'Latest delivery'));
+  if (project.delivery) {
+    delivery.append(el('p', '', `${project.delivery.title} · ${project.delivery.currentPhase} · ${project.delivery.status}`));
+  } else delivery.append(el('p', 'muted', 'No delivery summary was submitted.'));
+  const attention = el('section', 'detail-section');
+  attention.append(el('h4', '', 'Attention'));
+  if (!project.attention.length) attention.append(el('p', 'muted', 'No bounded attention items were submitted or derived.'));
+  else {
+    const list = el('ul', 'attention-list');
+    for (const item of project.attention) list.append(el('li', `attention-${item.severity}`, item.summary));
+    attention.append(list);
+  }
+  projectDetail.append(heading, evidence, delivery, attention);
+  projectDetail.focus();
+}
+
+function renderProjects() {
+  projectList.replaceChildren();
+  for (const project of state.portfolio.projects) {
+    const item = el('li');
+    const button = el('button', 'project-button');
+    button.type = 'button';
+    button.dataset.projectId = project.id;
+    button.setAttribute('aria-current', project.id === state.selectedId ? 'true' : 'false');
+    button.append(el('span', 'project-name', project.name), el('span', 'project-meta', `${project.freshness.state} · ${project.attention.length} attention`));
+    item.append(button);
+    projectList.append(item);
+  }
+}
+
+function resourceKey(resource) { return `${resource.id}@${resource.version}`; }
+
+function renderResourceDetail() {
+  const resource = state.resources?.releases.find((item) => resourceKey(item) === state.selectedResource);
+  resourceDetail.replaceChildren();
+  if (!resource) {
+    resourceDetail.append(el('p', 'empty-state', 'Choose an immutable release.'));
+    return;
+  }
+  const heading = el('header', 'detail-heading');
+  const title = el('div');
+  title.append(el('p', 'eyebrow', resource.kind.replaceAll('-', ' ').toUpperCase()), el('h3', '', resource.name));
+  heading.append(title, el('span', 'freshness freshness-current', `v${resource.version}`));
+  const identity = el('dl', 'evidence-grid');
+  identity.append(
+    evidenceRow('Resource ID', resource.id),
+    evidenceRow('Package digest', resource.digest),
+    evidenceRow('Publisher', `${resource.publisher.name} (${resource.publisher.id})`),
+    evidenceRow('EWAI compatibility', resource.compatibility.ewai),
+    evidenceRow('Package bounds', `${resource.fileCount} files · ${resource.totalBytes} bytes`),
+    evidenceRow('Published', resource.publishedAt),
+    evidenceRow('Receipt', resource.receiptId),
+  );
+  const boundary = el('section', 'detail-section');
+  boundary.append(el('h4', '', 'Authority boundary'), el('p', 'muted', 'This release is available to authenticated readers. A contributor must still download, verify, explicitly install, then select or apply it separately.'));
+  const chain = el('section', 'detail-section');
+  chain.append(el('h4', '', 'Retained versions'));
+  const versions = el('ul', 'attention-list');
+  for (const release of state.resources.releases.filter(({ id }) => id === resource.id)) {
+    versions.append(el('li', '', `v${release.version} · ${release.digest}`));
+  }
+  chain.append(versions);
+  resourceDetail.append(heading, identity, chain, boundary);
+  resourceDetail.focus();
+}
+
+function renderResources() {
+  resourceList.replaceChildren();
+  for (const resource of state.resources?.releases ?? []) {
+    const item = el('li');
+    const button = el('button', 'project-button');
+    button.type = 'button';
+    button.dataset.resourceKey = resourceKey(resource);
+    button.setAttribute('aria-current', resourceKey(resource) === state.selectedResource ? 'true' : 'false');
+    button.append(el('span', 'project-name', resource.name), el('span', 'project-meta', `${resource.kind.replaceAll('-', ' ')} · v${resource.version}`));
+    item.append(button); resourceList.append(item);
+  }
+  if (!(state.resources?.releases?.length)) resourceList.append(el('li', 'empty-state', 'No governed releases have been published.'));
+  renderResourceDetail();
+}
+
+async function loadResources(token) {
+  state.resources = await teamHubApi('/api/v1/resources', token);
+  state.selectedResource = state.resources.releases[0] ? resourceKey(state.resources.releases[0]) : null;
+  resourceRegistry.hidden = false;
+  renderResources();
+}
+
+async function loadPortfolio(token) {
+  message.textContent = 'Loading portfolio…';
+  try {
+    state.portfolio = await teamHubApi('/api/v1/portfolio', token);
+    state.selectedId = state.portfolio.projects[0]?.id ?? null;
+    portfolioSection.hidden = false;
+    renderSummary(); renderProjects(); renderDetail();
+    message.textContent = `Portfolio refreshed at ${state.portfolio.generatedAt}.`;
+  } catch (error) {
+    portfolioSection.hidden = true;
+    message.textContent = error.message;
+    throw error;
+  }
+}
+
+async function loadHubSurfaces(token) {
+  const results = await Promise.allSettled([loadPortfolio(token), loadResources(token)]);
+  if (results.some(({ status }) => status === 'fulfilled')) {
+    sessionStorage.setItem('ewai.team-hub.token', token);
+    message.textContent = 'Authenticated views refreshed.';
+    return;
+  }
+  sessionStorage.removeItem('ewai.team-hub.token');
+  throw results[0].reason;
+}
+
+document.querySelector('#accessForm').addEventListener('submit', (event) => {
+  event.preventDefault();
+  const token = tokenInput.value;
+  loadHubSurfaces(token).catch((error) => { message.textContent = error.message; });
+  tokenInput.value = '';
+});
+document.querySelector('#refreshPortfolio').addEventListener('click', () => loadPortfolio(sessionStorage.getItem('ewai.team-hub.token')).catch((error) => { message.textContent = error.message; }));
+document.querySelector('#refreshResources').addEventListener('click', () => loadResources(sessionStorage.getItem('ewai.team-hub.token')).catch((error) => { message.textContent = error.message; }));
+projectList.addEventListener('click', (event) => {
+  const button = event.target.closest('[data-project-id]');
+  if (!button) return;
+  state.selectedId = button.dataset.projectId;
+  renderProjects(); renderDetail();
+});
+resourceList.addEventListener('click', (event) => {
+  const button = event.target.closest('[data-resource-key]');
+  if (!button) return;
+  state.selectedResource = button.dataset.resourceKey;
+  renderResources();
+});
+
+teamHubApi('/health', '').then((health) => {
+  document.querySelector('#serviceState').textContent = `${health.status} · ${health.bind} · built-in TLS ${health.tls ? 'on' : 'off'}`;
+}).catch(() => { document.querySelector('#serviceState').textContent = 'Service health unavailable'; });
+
+const sessionToken = sessionStorage.getItem('ewai.team-hub.token');
+if (sessionToken) loadHubSurfaces(sessionToken).catch(() => {});

package/public/team-hub/index.html

@@ -0,0 +1,79 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>EWAI Team Hub</title>
+  <link rel="stylesheet" href="/styles.css">
+</head>
+<body>
+  <a class="skip-link" href="#main">Skip to portfolio</a>
+  <header class="masthead">
+    <div>
+      <p class="eyebrow">EWAI · TEAM HUB</p>
+      <h1>Connected portfolio</h1>
+    </div>
+    <div id="serviceState" class="service-state" aria-live="polite">Checking service…</div>
+  </header>
+
+  <main id="main">
+    <section class="access-panel" aria-labelledby="accessHeading">
+      <div>
+        <p class="eyebrow">SESSION ACCESS</p>
+        <h2 id="accessHeading">Open this portfolio</h2>
+        <p>The bearer token stays in this browser tab only. Team Hub does not persist it in browser storage.</p>
+      </div>
+      <form id="accessForm">
+        <label for="hubToken">Team Hub token</label>
+        <div class="input-row">
+          <input id="hubToken" name="token" type="password" autocomplete="off" required minlength="16">
+          <button type="submit">Load portfolio</button>
+        </div>
+      </form>
+    </section>
+
+    <section class="authority-note" aria-label="Authority boundary">
+      <strong>Read-only operational evidence.</strong>
+      <span>Team Hub cannot approve Build or Manual QA, accept risk, certify compliance, deploy or release.</span>
+    </section>
+
+    <section id="portfolio" class="portfolio" hidden aria-labelledby="portfolioHeading">
+      <header class="section-heading">
+        <div>
+          <p class="eyebrow">PORTFOLIO EVIDENCE</p>
+          <h2 id="portfolioHeading">Projects</h2>
+        </div>
+        <button id="refreshPortfolio" class="quiet-button" type="button">Refresh</button>
+      </header>
+      <div id="summary" class="summary-grid" aria-live="polite"></div>
+      <div class="portfolio-grid">
+        <nav aria-label="Connected projects">
+          <ul id="projectList" class="project-list"></ul>
+        </nav>
+        <article id="projectDetail" class="project-detail" tabindex="-1">
+          <p class="empty-state">Load the portfolio, then choose a project.</p>
+        </article>
+      </div>
+    </section>
+    <section id="resourceRegistry" class="resource-registry" hidden aria-labelledby="resourceRegistryHeading">
+      <header class="section-heading">
+        <div>
+          <p class="eyebrow">GOVERNED RESOURCES</p>
+          <h2 id="resourceRegistryHeading">Release catalogue</h2>
+          <p>Immutable organisation Blueprint and design-system releases. Publication is not project activation.</p>
+        </div>
+        <button id="refreshResources" class="quiet-button" type="button">Refresh resources</button>
+      </header>
+      <div class="release-chain" aria-label="Resource release chain">
+        <strong>Published</strong><span>→</span><strong>Downloaded</strong><span>→</span><strong>Verified</strong><span>→</span><strong>Installed</strong><span>→</span><strong>Select/apply separately</strong>
+      </div>
+      <div class="resource-grid">
+        <nav aria-label="Published resource releases"><ul id="resourceList" class="project-list"></ul></nav>
+        <article id="resourceDetail" class="project-detail" tabindex="-1"><p class="empty-state">Load the catalogue, then choose a release.</p></article>
+      </div>
+    </section>
+    <p id="message" class="message" role="status" aria-live="polite"></p>
+  </main>
+  <script type="module" src="/app.js"></script>
+</body>
+</html>

package/public/team-hub/styles.css

@@ -0,0 +1,90 @@
+:root {
+  color-scheme: light;
+  --ink: #172033;
+  --muted: #5f6b7b;
+  --line: #d8dee7;
+  --paper: #f5f7fa;
+  --surface: #ffffff;
+  --blue: #2556a8;
+  --blue-dark: #183c78;
+  --green: #216a52;
+  --amber: #8a5a13;
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+* { box-sizing: border-box; }
+body { margin: 0; color: var(--ink); background: var(--paper); line-height: 1.5; }
+button, input { font: inherit; }
+button { cursor: pointer; }
+.skip-link { position: fixed; top: 0; left: 1rem; transform: translateY(-120%); padding: .7rem 1rem; background: var(--ink); color: white; z-index: 10; }
+.skip-link:focus { transform: translateY(0); }
+.masthead { display: flex; align-items: flex-end; justify-content: space-between; gap: 2rem; padding: 2.5rem max(1.25rem, calc((100vw - 1180px) / 2)); background: #172033; color: white; border-bottom: 5px solid #4f80cc; }
+.masthead h1 { margin: .15rem 0 0; font-size: clamp(2rem, 5vw, 4rem); line-height: .98; letter-spacing: -.04em; }
+.eyebrow { margin: 0; color: #718099; font-size: .74rem; font-weight: 800; letter-spacing: .14em; }
+.masthead .eyebrow { color: #a9bddb; }
+.service-state { padding: .45rem .7rem; border: 1px solid #526177; color: #d7e2f1; font-size: .83rem; }
+main { width: min(1180px, calc(100% - 2.5rem)); margin: 2rem auto 4rem; }
+.access-panel { display: grid; grid-template-columns: minmax(0, 1fr) minmax(320px, .8fr); gap: 2rem; align-items: end; padding: 1.6rem; background: var(--surface); border: 1px solid var(--line); border-top: 4px solid var(--blue); }
+.access-panel h2, .section-heading h2 { margin: .2rem 0 .5rem; font-size: 1.55rem; }
+.access-panel p { margin-bottom: 0; color: var(--muted); }
+label { display: block; margin-bottom: .45rem; font-size: .82rem; font-weight: 800; }
+.input-row { display: flex; gap: .6rem; }
+input { width: 100%; min-width: 0; padding: .75rem .85rem; border: 1px solid #aab4c2; background: white; color: var(--ink); }
+button { padding: .72rem 1rem; border: 1px solid var(--blue); background: var(--blue); color: white; font-weight: 750; white-space: nowrap; }
+button:hover { background: var(--blue-dark); }
+button:focus-visible, input:focus-visible, [tabindex]:focus-visible, a:focus-visible { outline: 3px solid #e2a32a; outline-offset: 3px; }
+.authority-note { display: flex; gap: .6rem; margin: 1rem 0 2rem; padding: .85rem 1rem; border-left: 4px solid var(--amber); background: #fff9ee; color: #594319; }
+.section-heading { display: flex; align-items: center; justify-content: space-between; gap: 1rem; margin-bottom: 1rem; }
+.quiet-button { border-color: #9ca8b8; background: white; color: var(--ink); }
+.summary-grid { display: grid; grid-template-columns: repeat(4, 1fr); gap: .75rem; margin-bottom: .75rem; }
+.summary-card { display: flex; align-items: baseline; justify-content: space-between; padding: 1rem; border: 1px solid var(--line); background: var(--surface); }
+.summary-value { font-size: 1.6rem; font-weight: 850; }
+.summary-label { color: var(--muted); font-size: .8rem; text-transform: uppercase; letter-spacing: .08em; }
+.portfolio-grid { display: grid; grid-template-columns: minmax(260px, .62fr) minmax(0, 1.38fr); min-height: 460px; border: 1px solid var(--line); background: var(--surface); }
+.project-list { margin: 0; padding: 0; list-style: none; border-right: 1px solid var(--line); }
+.project-list li + li { border-top: 1px solid var(--line); }
+.project-button { display: block; width: 100%; padding: 1rem; border: 0; border-left: 4px solid transparent; background: white; color: var(--ink); text-align: left; white-space: normal; }
+.project-button:hover { background: #f4f7fb; }
+.project-button[aria-current="true"] { border-left-color: var(--blue); background: #eef4fc; }
+.project-name, .project-meta { display: block; }
+.project-name { font-weight: 800; }
+.project-meta { margin-top: .25rem; color: var(--muted); font-size: .8rem; }
+.project-detail { padding: 1.5rem; outline: none; }
+.detail-heading { display: flex; justify-content: space-between; align-items: flex-start; gap: 1rem; padding-bottom: 1rem; border-bottom: 1px solid var(--line); }
+.detail-heading h3 { margin: .2rem 0 0; font-size: 1.8rem; }
+.freshness { padding: .3rem .55rem; border: 1px solid currentColor; font-size: .75rem; font-weight: 800; text-transform: uppercase; }
+.freshness-current { color: var(--green); }
+.freshness-stale { color: var(--amber); }
+.evidence-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0; margin: 1rem 0; border: 1px solid var(--line); }
+.evidence-row { min-width: 0; padding: .75rem; border-bottom: 1px solid var(--line); }
+.evidence-row:nth-child(odd) { border-right: 1px solid var(--line); }
+dt { color: var(--muted); font-size: .72rem; font-weight: 800; text-transform: uppercase; letter-spacing: .06em; }
+dd { margin: .25rem 0 0; overflow-wrap: anywhere; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: .78rem; }
+.detail-section { padding-top: 1rem; border-top: 1px solid var(--line); }
+.detail-section h4 { margin: 0 0 .4rem; }
+.attention-list { padding-left: 1.2rem; }
+.muted, .empty-state, .message { color: var(--muted); }
+.message { min-height: 1.5rem; }
+.resource-registry { margin-top: 2rem; }
+.resource-registry .section-heading p { max-width: 720px; margin: .35rem 0 0; color: var(--muted); }
+.release-chain { display: flex; flex-wrap: wrap; align-items: center; gap: .55rem; margin-bottom: .75rem; padding: .8rem 1rem; border-left: 4px solid var(--green); background: #edf8f3; color: #154f3d; font-size: .78rem; }
+.release-chain span { color: #708078; }
+.resource-grid { display: grid; grid-template-columns: minmax(260px, .62fr) minmax(0, 1.38fr); min-height: 360px; border: 1px solid var(--line); background: var(--surface); }
+@media (max-width: 760px) {
+  .masthead, .access-panel, .portfolio-grid, .resource-grid { display: block; }
+  .masthead { padding: 1.5rem 1.25rem; }
+  .service-state { margin-top: 1rem; }
+  main { width: min(100% - 1.5rem, 1180px); }
+  .access-panel form { margin-top: 1rem; }
+  .input-row { display: block; }
+  .input-row button { width: 100%; margin-top: .6rem; }
+  .authority-note { display: block; }
+  .section-heading { align-items: stretch; flex-direction: column; }
+  .section-heading button { width: 100%; white-space: normal; }
+  .detail-heading { flex-direction: column; }
+  .summary-grid { grid-template-columns: repeat(2, 1fr); }
+  .project-list { border-right: 0; border-bottom: 1px solid var(--line); }
+  .evidence-grid { grid-template-columns: 1fr; }
+  .evidence-row:nth-child(odd) { border-right: 0; }
+  .project-detail, .project-list, .resource-registry { min-width: 0; }
+  .project-name, .project-meta, .detail-section, .attention-list { overflow-wrap: anywhere; }
+}

package/scripts/publication-check.mjs

@@ -0,0 +1,140 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, lstatSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const rules = [
+  ['personal-path', /\/(?:Users|home)\/(?!you(?:\/|\b)|example(?:\/|\b)|username(?:\/|\b)|user(?:\/|\b))[^\s/"'`<>]+\//],
+  ['internal-workspace', /(?:BusinessOps\/|\.claude\/projects\/|EngineeringWithAI\/Content\/Companion)/],
+  ['development-endpoint', /\b(?:api|our)\.dev\.backstory\.is\b/i],
+  ['internal-provenance', /\b(?:Added|Originally generated|Created from lessons|introduced|Last index refresh)\b[^\n]{0,140}\b20\d{2}-\d{2}-\d{2}\b/i],
+  ['private-key', /-----BEGIN (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/],
+  ['github-token', /\b(?:gh[pousr]_[A-Za-z0-9]{25,}|github_pat_[A-Za-z0-9_]{30,})\b/],
+  ['stripe-secret', /\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16,}\b/],
+  ['aws-access-key', /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/],
+  ['openai-key', /\bsk-(?:proj-)?[A-Za-z0-9_-]{30,}\b/],
+  ['google-key', /\bAIza[A-Za-z0-9_-]{30,}\b/],
+  ['npm-token', /\bnpm_[A-Za-z0-9]{30,}\b/],
+  ['telegram-token', /\b\d{8,12}:[A-Za-z0-9_-]{30,}\b/],
+  ['authenticated-url', /https?:\/\/[^\s/]+:[^\s/@]+@/],
+];
+
+function safePath(path) {
+  return typeof path === 'string' && path.length > 0 && !isAbsolute(path)
+    && !path.includes('\\') && !/[\x00-\x1f]/.test(path)
+    && !path.split('/').some(part => part === '..' || part === '.' || part === '');
+}
+
+function privateFile(path) {
+  if (/^\.ewai-pipeline\//.test(path)) return path !== '.ewai-pipeline/.gitignore';
+  if (/^(?:SPECS\/|src\/migration\/|packs\/personas\/premium\/)/.test(path)) return true;
+  if (/^config\/.*(?:source-manifest|migration-map|operation-parity)\.(?:json|ya?ml)$/.test(path)) return true;
+  if (/(?:^|\/)(?:\.env(?:\..+)?|\.npmrc|\.netrc|id_rsa|id_ed25519)$/.test(path)) {
+    return !/(?:^|\/)\.env\.(?:example|sample|template)$/.test(path);
+  }
+  return /\.(?:pem|key|p12|pfx|sqlite|sqlite3|db|sql|har|log|zip|tgz)$/i.test(path);
+}
+
+export function publicationIssues(path, content) {
+  if (!safePath(path)) return [{ file: '[unsafe path]', line: 0, category: 'unsafe-path' }];
+  const findings = privateFile(path) ? [{ file: path, line: 0, category: 'private-file' }] : [];
+  for (const [index, line] of String(content).split('\n').entries()) {
+    for (const [category, expression] of rules) {
+      if (expression.test(line)) findings.push({ file: path, line: index + 1, category });
+    }
+  }
+  return findings;
+}
+
+export function scanPublicationFiles(root, paths) {
+  const findings = [];
+  for (const path of [...new Set(paths)].sort()) {
+    if (!safePath(path)) {
+      findings.push(...publicationIssues(path, ''));
+      continue;
+    }
+    const absolute = resolve(root, path);
+    if (relative(resolve(root), absolute).startsWith('..')) {
+      findings.push({ file: '[unsafe path]', line: 0, category: 'unsafe-path' });
+      continue;
+    }
+    try {
+      const components = path.split('/');
+      let candidate = resolve(root);
+      let linked = false;
+      for (const component of components) {
+        candidate = resolve(candidate, component);
+        if (lstatSync(candidate).isSymbolicLink()) { linked = true; break; }
+      }
+      if (linked) {
+        findings.push({ file: path, line: 0, category: 'symlink' });
+        continue;
+      }
+      const stat = lstatSync(absolute);
+      if (!stat.isFile() || stat.size > 8 * 1024 * 1024) {
+        findings.push({ file: path, line: 0, category: 'unscannable-file' });
+        continue;
+      }
+      const pathIssues = publicationIssues(path, '');
+      if (pathIssues.length) { findings.push(...pathIssues); continue; }
+      findings.push(...publicationIssues(path, readFileSync(absolute).toString('utf8')));
+    } catch (error) {
+      findings.push({ file: path, line: 0, category: error.code === 'ENOENT' ? 'missing-file' : 'unreadable-file' });
+    }
+  }
+  return findings;
+}
+
+function repositoryCandidates(root) {
+  const listed = execFileSync('git', ['ls-files', '--cached', '--others', '--exclude-standard', '-z'], {
+    cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+  }).split('\0').filter(Boolean);
+  return [...new Set(listed)].filter(path => {
+    try { lstatSync(resolve(root, path)); return true; }
+    catch (error) { return error.code !== 'ENOENT'; }
+  });
+}
+
+export function checkPublication(root, { sourceOnly = false } = {}) {
+  const source = repositoryCandidates(root);
+  const findings = scanPublicationFiles(root, source);
+  let packedFiles = 0;
+  if (!sourceOnly) {
+    const cache = mkdtempSync(resolve(tmpdir(), 'ewai-publication-cache-'));
+    try {
+      const result = execFileSync('npm', ['pack', '--dry-run', '--json', '--ignore-scripts'], {
+        cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60_000,
+        env: { ...process.env, npm_config_cache: cache, npm_config_update_notifier: 'false' },
+      });
+      const manifest = JSON.parse(result);
+      if (!Array.isArray(manifest) || manifest.length !== 1 || !Array.isArray(manifest[0].files) || !manifest[0].files.length) {
+        throw new Error('Invalid package manifest');
+      }
+      const paths = manifest[0].files.map(file => file.path);
+      if (paths.some(path => typeof path !== 'string')) throw new Error('Invalid package path');
+      packedFiles = paths.length;
+      findings.push(...scanPublicationFiles(root, paths));
+    } catch {
+      findings.push({ file: 'package.json', line: 0, category: 'package-inspection-failed' });
+    } finally {
+      rmSync(cache, { recursive: true, force: true });
+    }
+  }
+  const unique = [...new Map(findings.map(finding => [JSON.stringify(finding), finding])).values()];
+  return { status: unique.length ? 'fail' : 'pass', sourceFiles: source.length, packedFiles, findings: unique };
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const selected = process.argv.indexOf('--project');
+  const root = selected < 0 ? resolve(dirname(fileURLToPath(import.meta.url)), '..') : resolve(process.argv[selected + 1] ?? '.');
+  const quiet = process.argv.includes('--quiet');
+  try {
+    const result = checkPublication(root, { sourceOnly: process.argv.includes('--source-only') });
+    if (!quiet || result.status !== 'pass') (quiet ? console.error : console.log)(JSON.stringify(result));
+    process.exitCode = result.status === 'pass' ? 0 : 1;
+  } catch {
+    (quiet ? console.error : console.log)(JSON.stringify({ status: 'fail', findings: [{ file: '[repository]', line: 0, category: 'source-inspection-failed' }] }));
+    process.exitCode = 1;
+  }
+}

package/scripts/setup.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { install } from '../src/install.mjs';
+
+const args = process.argv.slice(2);
+
+function option(name, fallback = '') {
+  const index = args.indexOf(name);
+  return index === -1 ? fallback : args[index + 1] ?? fallback;
+}
+
+const project = option('--project');
+const result = install({
+  scope: project ? 'project' : 'global',
+  projectRoot: project ? resolve(project) : '',
+  host: option('--host', 'auto'),
+  mode: option('--mode', project ? 'copy' : 'link'),
+  force: args.includes('--force')
+});
+
+console.log(JSON.stringify(result, null, 2));