@fraylabs/possible 0.1.9 → 0.2.0

package/src/outcome-format.mjs

@@ -0,0 +1,201 @@
+import { readFile, readdir } from "node:fs/promises";
+import { basename, join, relative, resolve } from "node:path";
+
+const SAFE_SLUG = /^[a-z0-9][a-z0-9-]*$/;
+const EXACT_REVISION = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const PRODUCT_ID = /^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/;
+const GITHUB_REPOSITORY = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const SAFE_REPOSITORY_PATH = /^(?:\.|[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*)$/;
+const MODEL_ROLES = new Set(["authorship", "execution", "review"]);
+const FILE_TYPES = new Set(["image", "video", "audio", "cad", "document", "data", "source", "archive", "other"]);
+const MANIFEST_KEYS = new Set(["schemaVersion", "slug", "files", "authoredAt", "author", "models", "requirements", "products", "skills", "inputs", "artifacts", "preview"]);
+
+const asObject = (value, context) => {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${context} must be a JSON object`);
+  return value;
+};
+
+const string = (value, context) => {
+  if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${context} must be a non-empty string`);
+  return value;
+};
+
+const exactKeys = (value, allowed, context) => {
+  for (const key of Object.keys(value)) if (!allowed.has(key)) throw new Error(`${context}.${key} is unsupported`);
+};
+
+const httpsUrl = (value, context) => {
+  const candidate = string(value, context);
+  let parsed;
+  try { parsed = new URL(candidate); } catch { throw new Error(`${context} must be an HTTPS URL`); }
+  if (parsed.protocol !== "https:") throw new Error(`${context} must be an HTTPS URL`);
+  return candidate;
+};
+
+const safeRelativePath = (value, context) => {
+  const candidate = string(value, context);
+  if (candidate.includes("\\") || candidate.startsWith("/") || candidate.split("/").some((part) => part === "" || part === "." || part === "..")) {
+    throw new Error(`${context} must be a safe repository-relative path`);
+  }
+  return candidate;
+};
+
+const validateFiles = (value, context) => {
+  if (value === undefined) return;
+  if (!Array.isArray(value) || value.length === 0) throw new Error(`${context} must be omitted or a non-empty array`);
+  const seen = new Set();
+  value.forEach((entry, index) => {
+    const file = asObject(entry, `${context}[${index}]`);
+    exactKeys(file, new Set(["type", "src", "label", "format"]), `${context}[${index}]`);
+    if (!FILE_TYPES.has(file.type)) throw new Error(`${context}[${index}].type is unsupported`);
+    const source = file.src?.startsWith("https://") ? httpsUrl(file.src, `${context}[${index}].src`) : safeRelativePath(file.src, `${context}[${index}].src`);
+    string(file.label, `${context}[${index}].label`);
+    if (file.format !== undefined) string(file.format, `${context}[${index}].format`);
+    if (seen.has(source)) throw new Error(`${context} contains duplicate source ${source}`);
+    seen.add(source);
+  });
+};
+
+export function validateOutcomeManifest(value, context = "outcome.json") {
+  const manifest = asObject(value, context);
+  exactKeys(manifest, MANIFEST_KEYS, context);
+  if (manifest.schemaVersion !== 3) throw new Error(`${context}.schemaVersion must be 3`);
+  if (!SAFE_SLUG.test(string(manifest.slug, `${context}.slug`))) throw new Error(`${context}.slug must be lowercase and hyphenated`);
+
+  const files = asObject(manifest.files, `${context}.files`);
+  exactKeys(files, new Set(["about", "prompt"]), `${context}.files`);
+  if (files.about !== "outcome.md" || files.prompt !== "prompt.md") throw new Error(`${context}.files must reference outcome.md and prompt.md`);
+
+  if (manifest.authoredAt !== null) {
+    const authoredAt = string(manifest.authoredAt, `${context}.authoredAt`);
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?(?:Z|[+-]\d{2}:\d{2})$/.test(authoredAt) || Number.isNaN(Date.parse(authoredAt))) {
+      throw new Error(`${context}.authoredAt must be null or an ISO 8601 timestamp with a timezone`);
+    }
+  }
+
+  const author = asObject(manifest.author, `${context}.author`);
+  exactKeys(author, new Set(["name", "url"]), `${context}.author`);
+  string(author.name, `${context}.author.name`);
+  httpsUrl(author.url, `${context}.author.url`);
+
+  if (!Array.isArray(manifest.models) || manifest.models.length === 0) throw new Error(`${context}.models must be a non-empty array`);
+  manifest.models.forEach((entry, index) => {
+    const model = asObject(entry, `${context}.models[${index}]`);
+    exactKeys(model, new Set(["provider", "model", "agent", "role"]), `${context}.models[${index}]`);
+    string(model.provider, `${context}.models[${index}].provider`);
+    string(model.model, `${context}.models[${index}].model`);
+    if (model.agent !== undefined) string(model.agent, `${context}.models[${index}].agent`);
+    if (!MODEL_ROLES.has(model.role)) throw new Error(`${context}.models[${index}].role is unsupported`);
+  });
+
+  if (!Array.isArray(manifest.requirements)) throw new Error(`${context}.requirements must be an array`);
+  const requirements = manifest.requirements.map((entry, index) => string(entry, `${context}.requirements[${index}]`));
+  if (new Set(requirements).size !== requirements.length) throw new Error(`${context}.requirements contains duplicates`);
+
+  if (manifest.products !== undefined) {
+    if (!Array.isArray(manifest.products) || manifest.products.length === 0) throw new Error(`${context}.products must be omitted or a non-empty array`);
+    for (const [index, product] of manifest.products.entries()) if (!PRODUCT_ID.test(string(product, `${context}.products[${index}]`))) throw new Error(`${context}.products[${index}] is invalid`);
+    if (new Set(manifest.products).size !== manifest.products.length) throw new Error(`${context}.products contains duplicates`);
+  }
+
+  if (manifest.skills !== undefined) {
+    if (!Array.isArray(manifest.skills) || manifest.skills.length === 0) throw new Error(`${context}.skills must be omitted or a non-empty array`);
+    for (const [index, entry] of manifest.skills.entries()) {
+      const skill = asObject(entry, `${context}.skills[${index}]`);
+      exactKeys(skill, new Set(["repository", "lastReviewedCommit", "directory"]), `${context}.skills[${index}]`);
+      if (!GITHUB_REPOSITORY.test(string(skill.repository, `${context}.skills[${index}].repository`))) throw new Error(`${context}.skills[${index}].repository is invalid`);
+      if (!EXACT_REVISION.test(string(skill.lastReviewedCommit, `${context}.skills[${index}].lastReviewedCommit`))) throw new Error(`${context}.skills[${index}].lastReviewedCommit must be an exact commit`);
+      const directory = string(skill.directory, `${context}.skills[${index}].directory`);
+      if (!SAFE_REPOSITORY_PATH.test(directory) || (directory !== "." && directory.split("/").some((part) => part === "." || part === ".."))) throw new Error(`${context}.skills[${index}].directory is invalid`);
+    }
+  }
+
+  validateFiles(manifest.inputs, `${context}.inputs`);
+  validateFiles(manifest.artifacts, `${context}.artifacts`);
+  if (manifest.preview !== undefined) asObject(manifest.preview, `${context}.preview`);
+  return manifest;
+}
+
+const plainInlineMarkdown = (value) => value
+  .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1")
+  .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+  .replace(/[*_~`]/g, "")
+  .replace(/\s+/g, " ")
+  .trim();
+
+export function parseOutcomeMarkdown(value, context = "outcome.md") {
+  const markdown = string(value, context).trim();
+  const lines = markdown.split(/\r?\n/);
+  const titleLine = lines[0] ?? "";
+  if (!titleLine.startsWith("# ") || titleLine.slice(2).trim().length === 0) throw new Error(`${context} must begin with one # title`);
+  if (lines.slice(1).some((line) => line.startsWith("# "))) throw new Error(`${context} must contain exactly one # title`);
+  let index = 1;
+  while (index < lines.length && lines[index]?.trim() === "") index += 1;
+  const summaryLines = [];
+  while (index < lines.length && lines[index]?.trim() !== "" && !lines[index]?.startsWith("## ")) {
+    summaryLines.push(lines[index]);
+    index += 1;
+  }
+  const summaryMarkdown = summaryLines.join("\n").trim();
+  if (!summaryMarkdown) throw new Error(`${context} must contain an opening summary after its title`);
+
+  const originalHeading = lines.findIndex((line) => line.trim().toLowerCase() === "## original request");
+  let originalPrompt;
+  if (originalHeading >= 0) {
+    const quoted = [];
+    for (const line of lines.slice(originalHeading + 1)) {
+      if (line.startsWith("## ")) break;
+      if (line.startsWith("> ")) quoted.push(line.slice(2));
+      else if (line === ">") quoted.push("");
+    }
+    const joined = quoted.join("\n").trim();
+    if (joined) originalPrompt = joined;
+  }
+  return {
+    title: plainInlineMarkdown(titleLine.slice(2)),
+    summary: plainInlineMarkdown(summaryMarkdown),
+    summaryMarkdown,
+    markdown,
+    ...(originalPrompt ? { originalPrompt } : {}),
+  };
+}
+
+export async function readOutcomeFolder(folder) {
+  const [manifestText, aboutText, promptText] = await Promise.all([
+    readFile(join(folder, "outcome.json"), "utf8"),
+    readFile(join(folder, "outcome.md"), "utf8"),
+    readFile(join(folder, "prompt.md"), "utf8"),
+  ]);
+  const manifest = validateOutcomeManifest(JSON.parse(manifestText), `${relative(process.cwd(), join(folder, "outcome.json")) || "outcome.json"}`);
+  if (basename(folder) !== manifest.slug) throw new Error(`${manifest.slug}: folder name must match outcome.json slug`);
+  const about = parseOutcomeMarkdown(aboutText, `${manifest.slug}/outcome.md`);
+  const executionPrompt = string(promptText, `${manifest.slug}/prompt.md`).trim();
+  return { slug: manifest.slug, folder, manifest, about, executionPrompt };
+}
+
+export async function discoverLocalOutcomes(repositoryRoot) {
+  const found = [];
+  async function walk(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    if (entries.some((entry) => entry.isFile() && entry.name === "outcome.json")) {
+      found.push(await readOutcomeFolder(directory));
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.isSymbolicLink() || entry.name === ".git" || entry.name === "node_modules") continue;
+      await walk(join(directory, entry.name));
+    }
+  }
+  await walk(resolve(repositoryRoot));
+  if (found.length === 0) throw new Error(`No Outcome folders found under ${repositoryRoot}`);
+  const identities = new Set();
+  for (const outcome of found) {
+    if (identities.has(outcome.slug)) throw new Error(`Duplicate Outcome slug: ${outcome.slug}`);
+    identities.add(outcome.slug);
+  }
+  return found.sort((left, right) => left.about.title.localeCompare(right.about.title));
+}
+
+export function relativeOutcomePath(repositoryRoot, folder) {
+  return relative(resolve(repositoryRoot), resolve(folder)).split("\\").join("/");
+}

package/src/sources.mjs

@@ -0,0 +1,174 @@
+import { createHash } from "node:crypto";
+import { isIP } from "node:net";
+import { parseOutcomeMarkdown, validateOutcomeManifest } from "./outcome-format.mjs";
+
+const MAX_OUTCOMES = 100;
+const MAX_DOCUMENT_BYTES = 1024 * 1024;
+const GITHUB_SHORTHAND = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/;
+
+function privateHostname(value) {
+  const hostname = value.toLowerCase().replace(/^\[|\]$/g, "");
+  if (hostname === "localhost" || hostname.endsWith(".localhost") || hostname.endsWith(".local")) return true;
+  if (isIP(hostname) === 4) {
+    const [first, second] = hostname.split(".").map(Number);
+    return first === 0 || first === 10 || first === 127 || first >= 224
+      || (first === 100 && second >= 64 && second <= 127)
+      || (first === 169 && second === 254)
+      || (first === 172 && second >= 16 && second <= 31)
+      || (first === 192 && second === 168)
+      || (first === 198 && (second === 18 || second === 19));
+  }
+  if (isIP(hostname) === 6) return hostname === "::" || hostname === "::1" || /^(?:fc|fd|fe[89ab])/i.test(hostname) || /^::ffff:(?:0\.|10\.|127\.|169\.254\.|172\.(?:1[6-9]|2\d|3[01])\.|192\.168\.)/.test(hostname);
+  return false;
+}
+
+function normalizedBaseUrl(value) {
+  const url = new URL(value);
+  if (url.protocol !== "https:") throw new Error("Publisher domains must use HTTPS");
+  url.hash = "";
+  url.search = "";
+  url.pathname = url.pathname.replace(/\/+$/, "");
+  return url;
+}
+
+export function parseOutcomeSource(value) {
+  const source = String(value ?? "").trim();
+  const shorthand = source.match(GITHUB_SHORTHAND);
+  if (shorthand) {
+    const owner = shorthand[1];
+    const repository = shorthand[2].replace(/\.git$/, "");
+    return { type: "github", locator: `${owner}/${repository}`, installUrl: `https://github.com/${owner}/${repository}` };
+  }
+  let url;
+  try { url = new URL(source); } catch { throw new Error("Source must be a GitHub owner/repository or an HTTPS publisher URL"); }
+  if (url.hostname.toLowerCase() === "github.com") {
+    const [owner, repository] = url.pathname.replace(/^\/+|\/+$/g, "").split("/");
+    if (!owner || !repository) throw new Error("GitHub sources must identify an owner and repository");
+    const cleanRepository = repository.replace(/\.git$/, "");
+    return { type: "github", locator: `${owner}/${cleanRepository}`, installUrl: `https://github.com/${owner}/${cleanRepository}` };
+  }
+  if (privateHostname(url.hostname)) throw new Error("Publisher source cannot use a local or private network address");
+  const base = normalizedBaseUrl(url.toString());
+  return { type: "well-known", locator: base.origin, installUrl: base.toString() };
+}
+
+async function responseText(response, context) {
+  if (!response.ok) throw new Error(`${context} returned HTTP ${response.status}`);
+  const declared = Number(response.headers.get("content-length") ?? 0);
+  if (declared > MAX_DOCUMENT_BYTES) throw new Error(`${context} exceeds the 1 MiB document limit`);
+  const text = await response.text();
+  if (Buffer.byteLength(text) > MAX_DOCUMENT_BYTES) throw new Error(`${context} exceeds the 1 MiB document limit`);
+  return text;
+}
+
+async function fetchJson(url, context, headers = {}) {
+  const response = await fetch(url, { headers: { accept: "application/json", ...headers }, redirect: "error" });
+  return JSON.parse(await responseText(response, context));
+}
+
+async function fetchText(url, context, headers = {}) {
+  const response = await fetch(url, { headers: { accept: "text/markdown,text/plain;q=0.9", ...headers }, redirect: "error" });
+  return responseText(response, context);
+}
+
+const digestDocuments = ({ manifestText, aboutText, promptText }) => `sha256:${createHash("sha256").update(manifestText).update("\0").update(aboutText).update("\0").update(promptText).digest("hex")}`;
+
+function resolvedRemoteOutcome({ manifestText, aboutText, promptText, manifestUrl, aboutUrl, promptUrl, repositoryPath }) {
+  const manifest = validateOutcomeManifest(JSON.parse(manifestText), `${manifestUrl}`);
+  const about = parseOutcomeMarkdown(aboutText, `${aboutUrl}`);
+  const prompt = promptText.trim();
+  if (!prompt) throw new Error(`${promptUrl} must contain the exact execution prompt`);
+  return {
+    slug: manifest.slug,
+    title: about.title,
+    summary: about.summary,
+    aboutMarkdown: about.markdown,
+    prompt,
+    manifest,
+    manifestUrl,
+    aboutUrl,
+    promptUrl,
+    repositoryPath,
+    contentHash: digestDocuments({ manifestText, aboutText, promptText }),
+  };
+}
+
+async function discoverGitHub(source, options) {
+  const headers = { "user-agent": "possible-cli" };
+  const token = options.githubToken ?? process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN;
+  if (token) headers.authorization = `Bearer ${token}`;
+  const repository = await fetchJson(`https://api.github.com/repos/${source.locator}`, `GitHub repository ${source.locator}`, headers);
+  if (repository.private !== false) throw new Error(`${source.locator} is not a public GitHub repository`);
+  const revisionRecord = await fetchJson(`https://api.github.com/repos/${source.locator}/commits/${encodeURIComponent(repository.default_branch)}`, `GitHub revision ${source.locator}`, headers);
+  const revision = String(revisionRecord.sha ?? "");
+  if (!/^[0-9a-f]{40}$/.test(revision)) throw new Error(`GitHub did not return an exact revision for ${source.locator}`);
+  const rawBase = `https://raw.githubusercontent.com/${source.locator}/${revision}/`;
+  const indexUrl = new URL("outcomes.json", rawBase).toString();
+  const index = await fetchJson(indexUrl, `${source.locator}/outcomes.json`, headers);
+  if (index?.schemaVersion !== 1 || !Array.isArray(index.outcomes)) throw new Error(`${source.locator}/outcomes.json must be a Possible publisher index with schemaVersion 1`);
+  if (index.outcomes.length === 0 || index.outcomes.length > MAX_OUTCOMES) throw new Error(`${source.locator}/outcomes.json must list between 1 and ${MAX_OUTCOMES} Outcomes`);
+  const outcomes = [];
+  for (const [indexPosition, entry] of index.outcomes.entries()) {
+    if (!entry || typeof entry !== "object" || typeof entry.url !== "string") throw new Error(`${source.locator}/outcomes.json outcomes[${indexPosition}] must contain a URL`);
+    const manifestUrl = new URL(entry.url, indexUrl);
+    if (manifestUrl.origin !== new URL(rawBase).origin || !manifestUrl.pathname.startsWith(new URL(rawBase).pathname)) throw new Error(`${source.locator}/outcomes.json Outcome URLs must stay inside the exact repository revision`);
+    const folderUrl = new URL("./", manifestUrl);
+    const aboutUrl = new URL("outcome.md", folderUrl).toString();
+    const promptUrl = new URL("prompt.md", folderUrl).toString();
+    const [manifestText, aboutText, promptText] = await Promise.all([
+      fetchText(manifestUrl.toString(), `Outcome manifest ${manifestUrl}`, headers),
+      fetchText(aboutUrl, `Outcome page ${aboutUrl}`, headers),
+      fetchText(promptUrl, `Outcome prompt ${promptUrl}`, headers),
+    ]);
+    const repositoryPath = decodeURIComponent(manifestUrl.pathname.slice(new URL(rawBase).pathname.length)).replace(/\/outcome\.json$/, "");
+    const outcome = resolvedRemoteOutcome({ manifestText, aboutText, promptText, manifestUrl: manifestUrl.toString(), aboutUrl, promptUrl, repositoryPath });
+    if (entry.slug !== undefined && entry.slug !== outcome.slug) throw new Error(`${source.locator}/outcomes.json slug does not match ${manifestUrl}`);
+    if (outcome.slug !== repositoryPath.split("/").filter(Boolean).at(-1)) throw new Error(`${manifestUrl} slug must match its folder name`);
+    outcomes.push(outcome);
+  }
+  if (new Set(outcomes.map(({ slug }) => slug)).size !== outcomes.length) throw new Error(`${source.locator}/outcomes.json contains duplicate Outcome slugs`);
+  return { ...source, revision, publisherName: index.publisher?.name ?? source.locator.split("/")[0], outcomes };
+}
+
+async function discoverWellKnown(source) {
+  const indexUrl = new URL("/.well-known/possible/outcomes.json", source.locator).toString();
+  const index = await fetchJson(indexUrl, `Possible index ${indexUrl}`);
+  if (index?.schemaVersion !== 1 || !Array.isArray(index.outcomes)) throw new Error(`${indexUrl} must be a Possible publisher index with schemaVersion 1`);
+  if (index.outcomes.length === 0 || index.outcomes.length > MAX_OUTCOMES) throw new Error(`${indexUrl} must list between 1 and ${MAX_OUTCOMES} Outcomes`);
+  const outcomes = [];
+  for (const [indexPosition, entry] of index.outcomes.entries()) {
+    if (!entry || typeof entry !== "object" || typeof entry.url !== "string") throw new Error(`${indexUrl} outcomes[${indexPosition}] must contain a URL`);
+    const manifestUrl = new URL(entry.url, indexUrl);
+    if (manifestUrl.protocol !== "https:" || manifestUrl.origin !== new URL(source.locator).origin) throw new Error(`${indexUrl} Outcome URLs must stay on the publisher origin`);
+    const folderUrl = new URL("./", manifestUrl);
+    const aboutUrl = new URL("outcome.md", folderUrl).toString();
+    const promptUrl = new URL("prompt.md", folderUrl).toString();
+    const [manifestText, aboutText, promptText] = await Promise.all([
+      fetchText(manifestUrl.toString(), `Outcome manifest ${manifestUrl}`),
+      fetchText(aboutUrl, `Outcome page ${aboutUrl}`),
+      fetchText(promptUrl, `Outcome prompt ${promptUrl}`),
+    ]);
+    const outcome = resolvedRemoteOutcome({ manifestText, aboutText, promptText, manifestUrl: manifestUrl.toString(), aboutUrl, promptUrl });
+    if (entry.slug !== undefined && entry.slug !== outcome.slug) throw new Error(`${indexUrl} slug does not match ${manifestUrl}`);
+    outcomes.push(outcome);
+  }
+  if (new Set(outcomes.map(({ slug }) => slug)).size !== outcomes.length) throw new Error(`${indexUrl} contains duplicate Outcome slugs`);
+  const revision = `sha256:${createHash("sha256").update(outcomes.map(({ contentHash }) => contentHash).sort().join("\n")).digest("hex")}`;
+  return { ...source, revision, publisherName: index.publisher?.name ?? new URL(source.locator).hostname, outcomes };
+}
+
+export async function discoverOutcomeSource(value, options = {}) {
+  const source = typeof value === "string" ? parseOutcomeSource(value) : value;
+  return source.type === "github" ? discoverGitHub(source, options) : discoverWellKnown(source);
+}
+
+export function publicSnapshot(discovery) {
+  return {
+    schemaVersion: 1,
+    source: { type: discovery.type, locator: discovery.locator, installUrl: discovery.installUrl, revision: discovery.revision },
+    publisherName: discovery.publisherName,
+    outcomes: discovery.outcomes.map(({ slug, title, summary, aboutMarkdown, prompt, manifest, manifestUrl, aboutUrl, promptUrl, repositoryPath, contentHash }) => ({
+      slug, title, summary, aboutMarkdown, prompt, manifest, manifestUrl, aboutUrl, promptUrl, repositoryPath, contentHash,
+    })),
+  };
+}