@fraylabs/possible 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fraylabs/possible",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Create, publish, discover, and reuse source-owned AI Outcomes",
   "keywords": [
     "codex",

package/src/directory.mjs

@@ -1,4 +1,9 @@
-const DEFAULT_ENDPOINT = "https://abutwsaahahtbtlopczi.supabase.co/functions/v1/outcome-directory";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+const DEFAULT_ENDPOINT = "https://reminiscent-lark-333.convex.site/api/outcomes";
 
 const directoryEndpoint = () => process.env.POSSIBLE_DIRECTORY_ENDPOINT?.trim() || DEFAULT_ENDPOINT;
 
@@ -11,6 +16,53 @@ async function requestDirectory(parameters, fetchImplementation = fetch) {
   return body;
 }
 
+function installationPath(environment = process.env) {
+  const home = environment.POSSIBLE_HOME ? resolve(environment.POSSIBLE_HOME) : join(homedir(), ".possible");
+  return join(home, "installation.json");
+}
+
+async function installationToken(environment = process.env) {
+  const path = installationPath(environment);
+  try {
+    const stored = JSON.parse(await readFile(path, "utf8"));
+    if (stored?.schemaVersion === 1 && typeof stored.id === "string") return stored.id;
+  } catch (error) {
+    if (error?.code !== "ENOENT" && !(error instanceof SyntaxError)) return undefined;
+  }
+  const id = randomUUID();
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify({ schemaVersion: 1, id }, null, 2)}\n`, { flag: "wx" });
+    return id;
+  } catch (error) {
+    if (error?.code === "EEXIST") return installationToken(environment);
+    return undefined;
+  }
+}
+
+async function recordUse(outcomeId, { fetchImplementation = fetch, environment = process.env } = {}) {
+  if (environment.CI || environment.POSSIBLE_TELEMETRY === "0") return;
+  const token = await installationToken(environment);
+  if (!token) return;
+  const endpoint = new URL(directoryEndpoint());
+  endpoint.pathname = `${endpoint.pathname.replace(/\/$/, "")}/use`;
+  endpoint.search = "";
+  try {
+    await fetchImplementation(endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json" },
+      body: JSON.stringify({
+        outcomeId,
+        visitorHash: createHash("sha256").update(token).digest("hex"),
+        source: "cli",
+        ci: false,
+      }),
+    });
+  } catch {
+    // Usage reporting never blocks access to a published prompt.
+  }
+}
+
 export async function searchOutcomes(query, options = {}) {
   const normalized = String(query ?? "").trim();
   if (!normalized) throw new Error("Search requires an ordinary-language query");
@@ -23,6 +75,7 @@ export async function fetchOutcome(id, options = {}) {
   if (!normalized) throw new Error("Fetch requires an Outcome ID from search results");
   const body = await requestDirectory({ id: normalized }, options.fetchImplementation);
   if (!body.outcome || typeof body.outcome.prompt !== "string") throw new Error("Possible returned an invalid Outcome");
+  await recordUse(body.outcome.id, options);
   return body.outcome;
 }
 
@@ -31,6 +84,7 @@ export function formatSearchResults(outcomes) {
   return `${outcomes.map((outcome, index) => [
     `${index + 1}. ${outcome.title}`,
     `   ${outcome.summary}`,
+    ...(outcome.primary_attribution ? [`   Primary: ${outcome.primary_attribution.kind === "product" ? outcome.primary_attribution.id : `${outcome.primary_attribution.repository}/${outcome.primary_attribution.directory}`}`] : []),
     `   ID: ${outcome.id}`,
     `   Source: ${outcome.source_locator}`,
   ].join("\n")).join("\n\n")}\n`;

package/src/index.mjs

@@ -8,7 +8,8 @@ import { addOutcomeSource, createOutcome, publishOutcomeSource, useOutcome, vali
 const HELP = `Possible CLI
 
 Usage:
-  possible create <slug>
+  possible create <slug> --product <owner/product>
+  possible create <slug> --skill <owner/repository> <directory> <commit>
   possible validate [directory]
   possible publish [owner/repository | https://publisher.example]
   possible search <ordinary-language query>
@@ -18,7 +19,7 @@ Usage:
   possible bookmark <command>
 
 Commands:
-  create    Create outcome.json, outcome.md, prompt.md, and media/ for one Outcome
+  create    Create one Outcome with its required primary Product or Skill
   validate  Validate every Outcome folder below a directory
   publish   Validate and submit one public publisher source; no account required
   search    Find relevant Outcomes in the live public directory
@@ -56,9 +57,12 @@ if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
     process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
     process.exitCode = 1;
   }
-} else if (args[0] === "create" && args.length === 2) {
+} else if (args[0] === "create" && ((args[2] === "--product" && args.length === 4) || (args[2] === "--skill" && args.length === 6))) {
   try {
-    const folder = await createOutcome(args[1]);
+    const primary = args[2] === "--product"
+      ? { kind: "product", id: args[3] }
+      : { kind: "skill", repository: args[3], directory: args[4], lastReviewedCommit: args[5] };
+    const folder = await createOutcome(args[1], { primary });
     process.stdout.write(`Created ${folder}\n`);
   } catch (error) {
     process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);

package/src/outcome-commands.mjs

@@ -7,10 +7,11 @@ import { discoverOutcomeSource } from "./sources.mjs";
 
 const execFileAsync = promisify(execFile);
 const SAFE_SLUG = /^[a-z0-9][a-z0-9-]*$/;
-const DEFAULT_PUBLISH_ENDPOINT = "https://abutwsaahahtbtlopczi.supabase.co/functions/v1/register-outcome-source";
+const DEFAULT_PUBLISH_ENDPOINT = "https://reminiscent-lark-333.convex.site/api/outcomes/register";
 
-export async function createOutcome(slug, { directory = process.cwd() } = {}) {
+export async function createOutcome(slug, { directory = process.cwd(), primary } = {}) {
   if (!SAFE_SLUG.test(slug ?? "")) throw new Error("Outcome slug must be lowercase and hyphenated");
+  if (!primary) throw new Error("Choose one primary attribution with --product or --skill");
   const root = resolve(directory);
   const indexPath = join(root, "outcomes.json");
   let publisherIndex = {
@@ -28,13 +29,14 @@ export async function createOutcome(slug, { directory = process.cwd() } = {}) {
   await mkdir(join(folder, "media"), { recursive: true });
   const manifestPath = join(folder, "outcome.json");
   const manifest = {
-    schemaVersion: 3,
+    schemaVersion: 4,
     slug,
     files: { about: "outcome.md", prompt: "prompt.md" },
     authoredAt: null,
     author: { name: "Replace with publisher name", url: "https://example.com" },
     models: [{ provider: "Replace with provider", model: "Replace with model", role: "execution" }],
     requirements: [],
+    primary,
   };
   await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { flag: "wx" });
   await writeFile(join(folder, "outcome.md"), `# Replace with Outcome name\n\nDescribe the concrete result in one clear opening paragraph.\n`, { flag: "wx" });

package/src/outcome-format.mjs

@@ -8,7 +8,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 BASE_MANIFEST_KEYS = ["schemaVersion", "slug", "files", "authoredAt", "author", "models", "requirements", "inputs", "artifacts", "preview"];
+const LEGACY_MANIFEST_KEYS = new Set([...BASE_MANIFEST_KEYS, "products", "skills"]);
+const MANIFEST_KEYS = new Set([...BASE_MANIFEST_KEYS, "primary", "secondary"]);
 
 const asObject = (value, context) => {
   if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${context} must be a JSON object`);
@@ -56,10 +58,59 @@ const validateFiles = (value, context) => {
   });
 };
 
+const validateSkillReference = (value, context, includeKind = false) => {
+  const skill = asObject(value, context);
+  exactKeys(skill, new Set(includeKind ? ["kind", "repository", "lastReviewedCommit", "directory"] : ["repository", "lastReviewedCommit", "directory"]), context);
+  if (includeKind && skill.kind !== "skill") throw new Error(`${context}.kind must be skill`);
+  if (!GITHUB_REPOSITORY.test(string(skill.repository, `${context}.repository`))) throw new Error(`${context}.repository is invalid`);
+  if (!EXACT_REVISION.test(string(skill.lastReviewedCommit, `${context}.lastReviewedCommit`))) throw new Error(`${context}.lastReviewedCommit must be an exact commit`);
+  const directory = string(skill.directory, `${context}.directory`);
+  if (!SAFE_REPOSITORY_PATH.test(directory) || (directory !== "." && directory.split("/").some((part) => part === "." || part === ".."))) throw new Error(`${context}.directory is invalid`);
+  return skill;
+};
+
+const validateAttribution = (value, context) => {
+  const attribution = asObject(value, context);
+  if (attribution.kind === "product") {
+    exactKeys(attribution, new Set(["kind", "id"]), context);
+    if (!PRODUCT_ID.test(string(attribution.id, `${context}.id`))) throw new Error(`${context}.id is invalid`);
+    return attribution;
+  }
+  if (attribution.kind === "skill") return validateSkillReference(attribution, context, true);
+  throw new Error(`${context}.kind must be product or skill`);
+};
+
+export const attributionKey = (attribution) => attribution.kind === "product"
+  ? `product:${attribution.id}`
+  : `skill:${attribution.repository}/${attribution.directory}`;
+
+export function normalizeOutcomeAttributions(manifest) {
+  if (manifest.schemaVersion === 4) {
+    const secondary = manifest.secondary ?? [];
+    const all = [manifest.primary, ...secondary];
+    return {
+      primary: manifest.primary,
+      secondary,
+      products: all.filter((item) => item.kind === "product").map((item) => item.id),
+      skills: all.filter((item) => item.kind === "skill").map(({ kind: _kind, ...skill }) => skill),
+    };
+  }
+  const legacy = [
+    ...(manifest.products ?? []).map((id) => ({ kind: "product", id })),
+    ...(manifest.skills ?? []).map((skill) => ({ kind: "skill", ...skill })),
+  ];
+  return {
+    primary: legacy[0] ?? null,
+    secondary: legacy.slice(1),
+    products: manifest.products ?? [],
+    skills: manifest.skills ?? [],
+  };
+}
+
 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 (manifest.schemaVersion !== 3 && manifest.schemaVersion !== 4) throw new Error(`${context}.schemaVersion must be 3 or 4`);
+  exactKeys(manifest, manifest.schemaVersion === 4 ? MANIFEST_KEYS : LEGACY_MANIFEST_KEYS, context);
   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`);
@@ -92,24 +143,27 @@ export function validateOutcomeManifest(value, context = "outcome.json") {
   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 (manifest.schemaVersion === 3 && 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 (manifest.schemaVersion === 3 && 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`);
+      validateSkillReference(entry, `${context}.skills[${index}]`);
     }
   }
 
+  if (manifest.schemaVersion === 4) {
+    const primary = validateAttribution(manifest.primary, `${context}.primary`);
+    if (manifest.secondary !== undefined && (!Array.isArray(manifest.secondary) || manifest.secondary.length === 0)) throw new Error(`${context}.secondary must be omitted or a non-empty array`);
+    const secondary = (manifest.secondary ?? []).map((entry, index) => validateAttribution(entry, `${context}.secondary[${index}]`));
+    const keys = [attributionKey(primary), ...secondary.map(attributionKey)];
+    if (new Set(keys).size !== keys.length) throw new Error(`${context} contains duplicate primary or secondary attributions`);
+  }
+
   validateFiles(manifest.inputs, `${context}.inputs`);
   validateFiles(manifest.artifacts, `${context}.artifacts`);
   if (manifest.preview !== undefined) asObject(manifest.preview, `${context}.preview`);

package/src/sources.d.mts

@@ -0,0 +1,36 @@
+export type OutcomeSource = {
+  type: "github" | "well-known";
+  locator: string;
+  installUrl: string;
+};
+
+export type DiscoveredOutcome = {
+  slug: string;
+  title: string;
+  summary: string;
+  aboutMarkdown: string;
+  prompt: string;
+  manifest: Record<string, unknown>;
+  manifestUrl: string;
+  aboutUrl: string;
+  promptUrl: string;
+  repositoryPath?: string;
+  contentHash: string;
+};
+
+export type OutcomeDiscovery = OutcomeSource & {
+  revision: string;
+  publisherName: string;
+  outcomes: DiscoveredOutcome[];
+};
+
+export type PublicOutcomeSnapshot = {
+  schemaVersion: 1;
+  source: OutcomeSource & { revision: string };
+  publisherName: string;
+  outcomes: DiscoveredOutcome[];
+};
+
+export function parseOutcomeSource(value: string): OutcomeSource;
+export function discoverOutcomeSource(value: string | OutcomeSource, options?: { githubToken?: string }): Promise<OutcomeDiscovery>;
+export function publicSnapshot(discovery: OutcomeDiscovery): PublicOutcomeSnapshot;