agentskeptic 1.0.4 → 1.1.1

package/scripts/emit-primary-marketing.cjs

@@ -0,0 +1,326 @@
+"use strict";
+
+const { readFileSync, writeFileSync, mkdirSync } = require("node:fs");
+const { join, dirname } = require("node:path");
+const { normalize, assertNextPublicOriginParity, MARKETING_PATH } = require("./origin.cjs");
+
+const ROOT = join(__dirname, "..");
+
+const OPENAPI_IN = join(ROOT, "schemas", "openapi-commercial-v1.in.yaml");
+const OPENAPI_OUT = join(ROOT, "schemas", "openapi-commercial-v1.yaml");
+const OPENAPI_PUBLIC = join(ROOT, "website", "public", "openapi-commercial-v1.yaml");
+const LLMS_PUBLIC = join(ROOT, "website", "public", "llms.txt");
+const LLMS_REPO_ROOT = join(ROOT, "llms.txt");
+const README_PATH = join(ROOT, "README.md");
+const PKG_PATH = join(ROOT, "package.json");
+
+const README_START = "<!-- public-product-anchors:start -->";
+const README_END = "<!-- public-product-anchors:end -->";
+const DISCOVERY_README_START = "<!-- discovery-acquisition-fold:start -->";
+const DISCOVERY_README_END = "<!-- discovery-acquisition-fold:end -->";
+const DISCOVERY_README_TITLE_START = "<!-- discovery-readme-title:start -->";
+const DISCOVERY_README_TITLE_END = "<!-- discovery-readme-title:end -->";
+
+const TOKENS = [
+  "__IDENTITY_ONE_LINER__",
+  "__DISTRIBUTION_CONTACT_URL__",
+  "__DISTRIBUTION_INTEGRATE_URL__",
+  "__DISTRIBUTION_REPO_URL__",
+  "__DISTRIBUTION_NPM_URL__",
+  "__OPENAPI_SELF_URL__",
+  "__SERVERS_ORIGIN__",
+];
+
+/**
+ * @param {string} haystack
+ * @param {string} needle
+ */
+function countOccurrences(haystack, needle) {
+  let n = 0;
+  let i = 0;
+  while (true) {
+    const j = haystack.indexOf(needle, i);
+    if (j === -1) break;
+    n++;
+    i = j + needle.length;
+  }
+  return n;
+}
+
+function validateOpenapiTemplate() {
+  const template = readFileSync(OPENAPI_IN, "utf8");
+  for (const tok of TOKENS) {
+    const c = countOccurrences(template, tok);
+    if (c !== 1) {
+      throw new Error(`openapi template: token ${tok} must appear exactly once, found ${c}`);
+    }
+  }
+}
+
+function escapeYamlDoubleQuotedOneLiner(s) {
+  return String(s).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+/**
+ * @param {Record<string, unknown>} anchors
+ */
+function distributionSsotBlobUrl(anchors) {
+  const u = String(anchors.gitRepositoryUrl);
+  const m = u.match(/github\.com\/([^/]+)\/([^/#?]+)/i);
+  if (!m) throw new Error("emit-primary-marketing: cannot derive SSOT blob URL from gitRepositoryUrl");
+  const repo = m[2].replace(/\.git$/i, "");
+  return `https://github.com/${m[1]}/${repo}/blob/main/docs/public-distribution.md`;
+}
+
+/**
+ * @param {string} line
+ * @param {string} origin
+ * @param {string} slug
+ */
+function expandCliFooterLine(line, origin, slug) {
+  const acquisitionUrl = `${origin}${slug}`;
+  const integrateUrl = `${origin}/integrate`;
+  let out = String(line)
+    .replace(/\{\{ORIGIN\}\}/g, origin)
+    .replace(/\{\{ACQUISITION_URL\}\}/g, acquisitionUrl)
+    .replace(/\{\{INTEGRATE_URL\}\}/g, integrateUrl);
+  if (out.includes("{{")) {
+    throw new Error(`emit-primary-marketing: unresolved placeholder in cliFollowupLines: ${line}`);
+  }
+  return out;
+}
+
+/**
+ * @param {Record<string, unknown>} anchors
+ * @param {Record<string, unknown>} discovery
+ */
+function writePublicDistributionGenerated(anchors, discovery) {
+  const ssotUrl = distributionSsotBlobUrl(anchors);
+  const origin = normalize(anchors.productionCanonicalOrigin);
+  const slug = String(discovery.slug);
+  const cliLines = /** @type {string[]} */ (discovery.cliFollowupLines);
+  const expanded = cliLines.map((l) => expandCliFooterLine(l, origin, slug));
+  expanded.push(`Distribution contract (SSOT): ${ssotUrl}`);
+  if (expanded.length > 6) {
+    throw new Error(
+      `emit-primary-marketing: distribution footer exceeds 6 lines (${expanded.length}); shorten cliFollowupLines`,
+    );
+  }
+  const returnParts = expanded.map((line) => `${JSON.stringify(`${line}\n`)}`);
+  const pkgRaw = readFileSync(PKG_PATH, "utf8");
+  const pkgJson = JSON.parse(pkgRaw);
+  const cliSemver = String(pkgJson.version ?? "").trim();
+  if (!cliSemver) {
+    throw new Error("emit-primary-marketing: package.json missing version");
+  }
+  const body = `// Generated by npm run emit-primary-marketing — do not hand edit.
+
+export const PUBLIC_DISTRIBUTION_SSOT_BLOB_URL = ${JSON.stringify(ssotUrl)};
+
+export const PUBLIC_CANONICAL_SITE_ORIGIN = ${JSON.stringify(origin)};
+
+export const AGENTSKEPTIC_CLI_SEMVER = ${JSON.stringify(cliSemver)};
+
+export function formatDistributionFooter(): string {
+  return ${returnParts.join("\n    + ")};
+}
+`;
+  writeFileSync(join(ROOT, "src", "publicDistribution.generated.ts"), body, "utf8");
+}
+
+/**
+ * @param {Record<string, unknown>} anchors
+ * @param {Record<string, unknown>} discovery
+ */
+function writeAgentsMd(anchors, discovery) {
+  const url = distributionSsotBlobUrl(anchors);
+  const origin = normalize(anchors.productionCanonicalOrigin);
+  const slug = String(discovery.slug);
+  const acquisitionUrl = `${origin}${slug}`;
+  const dp = require("./discovery-payload.lib.cjs");
+  const { owner, repo } = dp.parseGithubRepoFromUrl(String(anchors.gitRepositoryUrl));
+  const branch = dp.DISCOVERY_LLM_BRANCH;
+  const llmsRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${branch}/llms.txt`;
+  const openapiRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${branch}/schemas/openapi-commercial-v1.yaml`;
+  const body = `# AGENTS
+
+Normative **public distribution** and anchor sync: [\`docs/public-distribution.md\`](docs/public-distribution.md) (same content as ${url}).
+
+## Machine-readable product entrypoints
+
+- Committed \`llms.txt\` at repo root (same bytes as site \`/llms.txt\` after prebuild sync).
+- Raw GitHub \`llms.txt\`: ${llmsRaw}
+- OpenAPI YAML (repo raw): ${openapiRaw}
+- Acquisition page (canonical): ${acquisitionUrl}
+`;
+  writeFileSync(join(ROOT, "AGENTS.md"), body, "utf8");
+}
+
+function syncPrimaryMarketing() {
+  const discoveryLib = require("./discovery-acquisition.lib.cjs");
+  discoveryLib.validateDiscoveryAcquisition(ROOT);
+  const pm = discoveryLib.loadDiscoveryAcquisition(ROOT);
+  const anchors = pm;
+  const discovery = pm;
+
+  validateOpenapiTemplate();
+
+  const escaped = escapeYamlDoubleQuotedOneLiner(anchors.identityOneLiner);
+  const canonicalOrigin = normalize(anchors.productionCanonicalOrigin);
+  const openapiSelfCanonical = `${canonicalOrigin}/openapi-commercial-v1.yaml`;
+
+  const envUrl = process.env.NEXT_PUBLIC_APP_URL;
+  const effectivePublicOrigin =
+    typeof envUrl === "string" && envUrl.trim() ? envUrl.trim() : anchors.productionCanonicalOrigin;
+  const publicOriginNormalized = normalize(effectivePublicOrigin);
+  const openapiSelfEffective = `${publicOriginNormalized}/openapi-commercial-v1.yaml`;
+
+  const integrateUrl = `${canonicalOrigin}/integrate`;
+
+  const template = readFileSync(OPENAPI_IN, "utf8");
+  let mid = template;
+  mid = mid.replace("__IDENTITY_ONE_LINER__", escaped);
+  mid = mid.replace("__DISTRIBUTION_CONTACT_URL__", canonicalOrigin);
+  mid = mid.replace("__DISTRIBUTION_INTEGRATE_URL__", integrateUrl);
+  mid = mid.replace("__DISTRIBUTION_REPO_URL__", anchors.gitRepositoryUrl);
+  mid = mid.replace("__DISTRIBUTION_NPM_URL__", anchors.npmPackageUrl);
+
+  const repoYaml = mid
+    .replace("__SERVERS_ORIGIN__", canonicalOrigin)
+    .replace("__OPENAPI_SELF_URL__", openapiSelfCanonical);
+  writeFileSync(OPENAPI_OUT, repoYaml, "utf8");
+
+  mkdirSync(dirname(OPENAPI_PUBLIC), { recursive: true });
+  const publicYaml = mid
+    .replace("__SERVERS_ORIGIN__", publicOriginNormalized)
+    .replace("__OPENAPI_SELF_URL__", openapiSelfEffective);
+  writeFileSync(OPENAPI_PUBLIC, publicYaml, "utf8");
+
+  const discoveryPayload = require("./discovery-payload.lib.cjs");
+  const discoveryPayloadObj = discoveryPayload.buildDiscoveryPayload(ROOT);
+  const llmsNormalized = discoveryPayload.renderLlmsTextFromPayload(discoveryPayloadObj);
+
+  mkdirSync(dirname(LLMS_PUBLIC), { recursive: true });
+  writeFileSync(LLMS_PUBLIC, llmsNormalized, "utf8");
+  writeFileSync(LLMS_REPO_ROOT, llmsNormalized, "utf8");
+
+  const pkgRaw = readFileSync(PKG_PATH, "utf8");
+  const pkg = JSON.parse(pkgRaw);
+  pkg.description = String(discovery.pageMetadata.description);
+  pkg.repository = { type: "git", url: anchors.gitRepositoryGitUrl };
+  pkg.homepage = `${canonicalOrigin}${String(discovery.slug)}`;
+  pkg.bugs = { url: anchors.bugsUrl };
+  pkg.keywords = anchors.keywords;
+  writeFileSync(PKG_PATH, JSON.stringify(pkg, null, 2) + "\n", "utf8");
+
+  let readme = readFileSync(README_PATH, "utf8");
+  if (!readme.includes(DISCOVERY_README_TITLE_START) || !readme.includes(DISCOVERY_README_TITLE_END)) {
+    throw new Error("README.md must contain discovery-readme-title markers");
+  }
+  const titleBody = `# ${String(discovery.readmeTitle)}`;
+  const titleBlock = `${DISCOVERY_README_TITLE_START}\n${titleBody}\n${DISCOVERY_README_TITLE_END}`;
+  const titleRe = new RegExp(
+    `${DISCOVERY_README_TITLE_START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${DISCOVERY_README_TITLE_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`,
+  );
+  if (!titleRe.test(readme)) {
+    throw new Error("README: could not match discovery-readme-title region");
+  }
+  readme = readme.replace(titleRe, titleBlock);
+
+  if (!readme.includes(DISCOVERY_README_START) || !readme.includes(DISCOVERY_README_END)) {
+    throw new Error("README.md must contain discovery-acquisition-fold markers");
+  }
+  const foldBody = discoveryLib.buildDiscoveryFoldBody(discovery, canonicalOrigin);
+  const discBlock = `${DISCOVERY_README_START}\n${foldBody}\n${DISCOVERY_README_END}`;
+  const discRe = new RegExp(
+    `${DISCOVERY_README_START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${DISCOVERY_README_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`,
+  );
+  if (!discRe.test(readme)) {
+    throw new Error("README: could not match discovery-acquisition-fold region");
+  }
+  readme = readme.replace(discRe, discBlock);
+
+  if (!readme.includes(README_START) || !readme.includes(README_END)) {
+    throw new Error("README.md must contain public-product-anchors markers");
+  }
+  const pl = discoveryPayloadObj.links;
+  const inner = [
+    anchors.identityOneLiner,
+    "",
+    `- **Repository:** ${anchors.gitRepositoryUrl}`,
+    `- **npm package:** ${anchors.npmPackageUrl}`,
+    `- **Canonical site:** ${canonicalOrigin}`,
+    `- **Integrate:** ${integrateUrl}`,
+    `- **OpenAPI (canonical):** ${openapiSelfCanonical}`,
+    `- **llms.txt (agents, site):** ${canonicalOrigin}/llms.txt`,
+    `- **llms.txt (repo, raw):** ${pl.llmsRaw}`,
+    `- **llms.txt (repo, blob):** ${pl.llmsBlob}`,
+    "",
+  ].join("\n");
+  const block = `${README_START}\n${inner}\n${README_END}`;
+  const re = new RegExp(
+    `${README_START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${README_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`,
+  );
+  if (!re.test(readme)) {
+    throw new Error("README: could not match public-product-anchors region");
+  }
+  readme = readme.replace(re, block);
+  writeFileSync(README_PATH, readme, "utf8");
+
+  writePublicDistributionGenerated(anchors, discovery);
+  writeAgentsMd(anchors, discovery);
+}
+
+function validateForCheck() {
+  const discoveryLib = require("./discovery-acquisition.lib.cjs");
+  discoveryLib.validateDiscoveryAcquisition(ROOT);
+  validateOpenapiTemplate();
+  const pm = JSON.parse(readFileSync(MARKETING_PATH, "utf8"));
+  const required = [
+    "identityOneLiner",
+    "productionCanonicalOrigin",
+    "gitRepositoryUrl",
+    "gitRepositoryGitUrl",
+    "npmPackageUrl",
+    "bugsUrl",
+    "keywords",
+  ];
+  for (const k of required) {
+    if (pm[k] === undefined || pm[k] === null) {
+      throw new Error(`marketing: missing ${k}`);
+    }
+  }
+  if (!Array.isArray(pm.keywords) || pm.keywords.length === 0) {
+    throw new Error("marketing: keywords must be a non-empty array");
+  }
+}
+
+function main() {
+  validateForCheck();
+  if (process.argv.includes("--check")) {
+    return;
+  }
+  syncPrimaryMarketing();
+}
+
+/** @deprecated use syncPrimaryMarketing */
+const syncPublicProductAnchors = syncPrimaryMarketing;
+/** @deprecated use validateForCheck */
+const validateAnchors = validateForCheck;
+
+module.exports = {
+  validateAnchors,
+  syncPublicProductAnchors,
+  syncPrimaryMarketing,
+  assertNextPublicOriginParity,
+  normalize,
+};
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : e);
+    process.exit(1);
+  }
+}

package/scripts/origin.cjs

@@ -0,0 +1,52 @@
+"use strict";
+
+const { readFileSync } = require("node:fs");
+const { join } = require("node:path");
+
+const ROOT = join(__dirname, "..");
+const MARKETING_PATH = join(ROOT, "config", "marketing.json");
+
+/**
+ * @param {string} s
+ */
+function normalize(s) {
+  const t = String(s).trim();
+  if (!t) throw new Error("normalize: empty origin");
+  const u = new URL(t);
+  return u.origin;
+}
+
+function isLoopbackOrigin(raw) {
+  try {
+    const u = new URL(normalize(raw));
+    const h = u.hostname.toLowerCase();
+    return h === "localhost" || h === "127.0.0.1" || h === "::1" || h === "[::1]";
+  } catch {
+    return false;
+  }
+}
+
+function readProductionCanonicalOrigin() {
+  const pm = JSON.parse(readFileSync(MARKETING_PATH, "utf8"));
+  return String(pm.productionCanonicalOrigin);
+}
+
+function assertNextPublicOriginParity() {
+  const canonicalFromJson = readProductionCanonicalOrigin();
+  const skip = process.env.NODE_ENV !== "production" || process.env.VERCEL_ENV === "preview";
+  if (skip) return;
+  const url = String(process.env.NEXT_PUBLIC_APP_URL || "").trim();
+  if (!url) return;
+  if (normalize(url) !== normalize(canonicalFromJson)) {
+    if (process.env.VERCEL_ENV !== "production" && isLoopbackOrigin(url)) return;
+    throw new Error("NEXT_PUBLIC_APP_URL must equal productionCanonicalOrigin");
+  }
+}
+
+module.exports = {
+  normalize,
+  assertNextPublicOriginParity,
+  MARKETING_PATH,
+  /** @deprecated use MARKETING_PATH */
+  PRIMARY_MARKETING_PATH: MARKETING_PATH,
+};

package/scripts/public-product-anchors.cjs

@@ -0,0 +1,3 @@
+"use strict";
+/** @deprecated Re-export — use `emit-primary-marketing.cjs` and `config/marketing.json`. */
+module.exports = require("./emit-primary-marketing.cjs");

package/scripts/validate-marketing.cjs

@@ -0,0 +1,156 @@
+"use strict";
+
+const { readFileSync } = require("node:fs");
+const { join } = require("node:path");
+
+const BANNED = /\b(crossing success|PatternComplete|IntegrateSpine|Outcome Certificate|AC-)\b/i;
+
+const URL_IN_TEXT = /https?:\/\/[^[\s<>"')]+/gi;
+
+/**
+ * True if the string contains a URL whose host is GitHub (github.com or a subdomain).
+ * Uses URL parsing so substrings like "evil.com/.../github.com" do not false-positive.
+ * @param {string} s
+ */
+function textContainsGithubHostUrl(s) {
+  for (const m of s.matchAll(URL_IN_TEXT)) {
+    try {
+      const { hostname } = new URL(m[0]);
+      if (hostname === "github.com" || hostname.endsWith(".github.com")) {
+        return true;
+      }
+    } catch {
+      // ignore invalid URL fragments
+    }
+  }
+  return false;
+}
+
+/**
+ * @param {string} root
+ */
+function loadMarketing(root) {
+  const p = join(root, "config", "marketing.json");
+  return JSON.parse(readFileSync(p, "utf8"));
+}
+
+/**
+ * @param {string} s
+ */
+function wordCount(s) {
+  return String(s)
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean).length;
+}
+
+/**
+ * @param {Record<string, unknown>} m
+ */
+function validateMarketingValue(m) {
+  if (m.schemaVersion !== 1) {
+    throw new Error("marketing: schemaVersion must be 1");
+  }
+  const required = [
+    "slug",
+    "identityOneLiner",
+    "productionCanonicalOrigin",
+    "gitRepositoryUrl",
+    "gitRepositoryGitUrl",
+    "npmPackageUrl",
+    "bugsUrl",
+    "keywords",
+    "heroTitle",
+    "heroSubtitle",
+    "visitorProblemAnswer",
+    "heroOutcome",
+    "heroMechanism",
+    "guaranteeFootnote",
+    "pageMetadata",
+    "readmeFold",
+    "shareableTerminalDemo",
+    "cliFollowupLines",
+    "r2",
+    "site",
+    "integratePage",
+    "problemIndex",
+    "llms",
+  ];
+  for (const k of required) {
+    if (m[k] === undefined || m[k] === null) {
+      throw new Error(`marketing: missing required key ${k}`);
+    }
+  }
+  if (!Array.isArray(m.keywords) || m.keywords.length === 0) {
+    throw new Error("marketing: keywords must be a non-empty array");
+  }
+  const ho = String(m.heroOutcome);
+  if (wordCount(ho) > 20) {
+    throw new Error(`marketing: heroOutcome must be at most 20 words (got ${wordCount(ho)})`);
+  }
+  if (String(m.heroMechanism).length > 200) {
+    throw new Error("marketing: heroMechanism must be at most 200 characters");
+  }
+  for (const field of [ho, String(m.heroMechanism)]) {
+    if (BANNED.test(field)) {
+      throw new Error(`marketing: banned term in home hero text: ${field.slice(0, 80)}`);
+    }
+  }
+  const g = String(m.guaranteeFootnote);
+  if (!g.toLowerCase().includes("read-only")) {
+    throw new Error("marketing: guaranteeFootnote must mention read-only");
+  }
+  if (textContainsGithubHostUrl(g)) {
+    throw new Error("marketing: guaranteeFootnote must not include a GitHub URL (site-local copy only)");
+  }
+  if (g.toLowerCase().includes("causality")) {
+    throw new Error("marketing: guaranteeFootnote must not contain the word causality");
+  }
+  const cmd = String(m.integratePage.packLedCommand);
+  if (!cmd.includes("agentskeptic crossing")) {
+    throw new Error("marketing: packLedCommand must include agentskeptic crossing");
+  }
+  if (!cmd.includes("--events")) {
+    throw new Error("marketing: packLedCommand must be pack-led (--events)");
+  }
+  if (!cmd.includes("tools.json")) {
+    throw new Error("marketing: packLedCommand must reference tools.json");
+  }
+  if (!Array.isArray(m.integratePage.requirements) || m.integratePage.requirements.length < 1) {
+    throw new Error("marketing: integratePage.requirements must be a non-empty array");
+  }
+  if (m.integratePage.requirements.length < 1 || m.integratePage.requirements.length > 5) {
+    throw new Error("marketing: integratePage.requirements must have 1–5 items");
+  }
+  const v = String(m.visitorProblemAnswer);
+  if (v.toLowerCase().includes("causality")) {
+    throw new Error("marketing: visitorProblemAnswer must not contain causality");
+  }
+  const demo = m.shareableTerminalDemo;
+  if (demo && String(demo.transcript).includes("```")) {
+    throw new Error("marketing: shareableTerminalDemo.transcript must not contain ```");
+  }
+  if (!m.readmeFold || !Array.isArray(m.readmeFold.templateLines)) {
+    throw new Error("marketing: readmeFold.templateLines required");
+  }
+  return m;
+}
+
+/**
+ * @param {string} root
+ */
+function validateMarketing(root) {
+  return validateMarketingValue(loadMarketing(root));
+}
+
+if (require.main === module) {
+  try {
+    validateMarketing(join(__dirname, ".."));
+    process.exit(0);
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : e);
+    process.exit(1);
+  }
+}
+
+module.exports = { validateMarketing, validateMarketingValue, loadMarketing };