@fraylabs/possible 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fraylabs/possible",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Create, publish, discover, and reuse source-owned AI Outcomes",
   "keywords": [
     "codex",
@@ -23,15 +23,10 @@
   "bin": {
     "possible": "src/index.mjs"
   },
-  "files": [
-    "assets/possible",
-    "src"
-  ],
+  "files": ["src"],
   "scripts": {
-    "build": "node scripts/sync-skill.mjs",
-    "test": "node --test test/*.test.mjs",
-    "sync:skill": "node scripts/sync-skill.mjs",
-    "prepack": "node scripts/sync-skill.mjs"
+    "build": "node --check src/index.mjs && node --check src/directory.mjs",
+    "test": "node --test test/*.test.mjs"
   },
   "engines": {
     "node": ">=22"

package/src/directory.mjs

@@ -0,0 +1,37 @@
+const DEFAULT_ENDPOINT = "https://abutwsaahahtbtlopczi.supabase.co/functions/v1/outcome-directory";
+
+const directoryEndpoint = () => process.env.POSSIBLE_DIRECTORY_ENDPOINT?.trim() || DEFAULT_ENDPOINT;
+
+async function requestDirectory(parameters, fetchImplementation = fetch) {
+  const url = new URL(directoryEndpoint());
+  for (const [name, value] of Object.entries(parameters)) url.searchParams.set(name, value);
+  const response = await fetchImplementation(url, { headers: { accept: "application/json" } });
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok) throw new Error(body.error || `Possible directory returned HTTP ${response.status}`);
+  return body;
+}
+
+export async function searchOutcomes(query, options = {}) {
+  const normalized = String(query ?? "").trim();
+  if (!normalized) throw new Error("Search requires an ordinary-language query");
+  const body = await requestDirectory({ q: normalized, limit: "5" }, options.fetchImplementation);
+  return Array.isArray(body.outcomes) ? body.outcomes : [];
+}
+
+export async function fetchOutcome(id, options = {}) {
+  const normalized = String(id ?? "").trim();
+  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");
+  return body.outcome;
+}
+
+export function formatSearchResults(outcomes) {
+  if (!outcomes.length) return "No matching Outcomes found.\n";
+  return `${outcomes.map((outcome, index) => [
+    `${index + 1}. ${outcome.title}`,
+    `   ${outcome.summary}`,
+    `   ID: ${outcome.id}`,
+    `   Source: ${outcome.source_locator}`,
+  ].join("\n")).join("\n\n")}\n`;
+}

package/src/index.mjs

@@ -2,25 +2,27 @@
 
 import process from "node:process";
 import { runBookmarkCommand } from "./bookmarks.mjs";
-import { installPossibleSkill } from "./init.mjs";
+import { fetchOutcome, formatSearchResults, searchOutcomes } from "./directory.mjs";
 import { addOutcomeSource, createOutcome, publishOutcomeSource, useOutcome, validateOutcomes } from "./outcome-commands.mjs";
 
 const HELP = `Possible CLI
 
 Usage:
-  possible init
   possible create <slug>
   possible validate [directory]
   possible publish [owner/repository | https://publisher.example]
+  possible search <ordinary-language query>
+  possible fetch <outcome-id>
   possible add <owner/repository | https://publisher.example>
   possible use <source>@<slug>
   possible bookmark <command>
 
 Commands:
-  init      Install the optional Possible prompt-preparation skill into this project
   create    Create outcome.json, outcome.md, prompt.md, and media/ for one Outcome
   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
+  fetch     Print one directory Outcome's exact prompt
   add       Discover a public source and save it to .possible/sources.json
   use       Print one exact execution prompt to standard output
   bookmark  add | list | remove locally saved Outcome slugs
@@ -38,6 +40,22 @@ 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] === "search" && args.length >= 2) {
+  try {
+    const outcomes = await searchOutcomes(args.slice(1).join(" "));
+    process.stdout.write(formatSearchResults(outcomes));
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+} else if (args[0] === "fetch" && args.length === 2) {
+  try {
+    const outcome = await fetchOutcome(args[1]);
+    process.stdout.write(`${outcome.prompt}\n`);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
 } else if (args[0] === "create" && args.length === 2) {
   try {
     const folder = await createOutcome(args[1]);
@@ -81,15 +99,7 @@ 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.length !== 1 || args[0] !== "init") {
+} else {
   process.stderr.write(`Unknown command: ${args.join(" ")}\n\n${HELP}`);
   process.exitCode = 1;
-} else {
-  try {
-    const result = await installPossibleSkill();
-    process.stdout.write(`${result.changed ? "Possible installed" : "Possible is already installed"} at ${result.installPath}\n\nOpen Codex in this project and type:\n\n  $possible\n`);
-  } catch (error) {
-    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
-    process.exitCode = 1;
-  }
 }

package/assets/possible/SKILL.md

@@ -1,117 +0,0 @@
----
-name: possible
-description: Discover proven Outcomes and turn a rough request into one complete execution prompt for a fresh agent. Also author and validate source-owned Outcomes for Possible.
----
-
-# Possible
-
-Possible connects three things:
-
-- the user's **original prompt**;
-- the complete **execution prompt** sent to a working agent;
-- the resulting **Outcome**.
-
-An Outcome is precedent to inspect and remix, not a rigid workflow. Preserve useful creative freedom while giving a fresh agent the context, current methods, and concrete inputs it needs.
-
-## Discover before writing
-
-Preserve the user's original prompt verbatim. Determine whether they want to browse possibilities, prepare a prompt, execute work, or publish completed work.
-
-For browsing or execution, call `search_outcomes` using ordinary language. Show up to five relevant Outcomes when the user is browsing. When preparing work, fetch the strongest candidates with `fetch_outcome` and read their exact prompts. Search scores indicate text similarity, not quality.
-
-Use Outcomes as concrete precedent. If none fit, use current primary sources rather than forcing an unrelated example. Prefer official documentation, current source repositories and registries, then reproducible community examples. Check volatile information at run time. Popularity is a discovery signal, not proof that an Outcome is good.
-
-## Resolve consequential unknowns
-
-Collect only what can materially improve execution:
-
-- the intended result, audience, use, and strong preferences;
-- supplied files, measurements, references, credentials, and constraints;
-- required inputs that the executor cannot safely invent;
-- relevant prior Outcomes and what they actually produced;
-- current Products, Skills, tools, environment, permissions, and limits;
-- what the user will inspect to decide that the result is finished.
-
-Ask the fewest questions necessary. Discover safe facts yourself. Infer harmless aesthetic details when a restrained default is sufficient. Do not turn the conversation into a form.
-
-## Prepare one execution prompt
-
-Write one readable, self-contained prompt for a fresh agent. It should naturally state:
-
-- the exact result and who it is for;
-- relevant user context and supplied materials;
-- concrete requirements and preferences;
-- current Products, Skills, or tools that matter;
-- deliverables and where to place them;
-- constraints, permissions, and separately authorized external actions;
-- what the user will inspect to judge the result;
-- unknowns the executor must preserve rather than invent.
-
-Adapt prior prompts to the current request, date, model, environment, and evidence. Never substitute a summary for a strong full prompt. Never claim an old method is current without checking. Keep the published prompt distinct from the new prompt you prepare.
-
-Before handoff, confirm that a fresh agent can start without hidden conversation history, missing essential files, consequential unresolved choices, unsupported current claims, or unclear success conditions. Research further or ask one focused question if it cannot.
-
-Show the proposed execution prompt and name the prior Outcomes and current official sources that materially shaped it.
-
-## Hand off once
-
-After approval, send the execution prompt unchanged to a fresh subagent when that capability is available. Include explicit paths or attachments for every supplied file. One-shot means complete starting context; it does not forbid the executor from inspecting, testing, or repairing its work.
-
-If fresh subagents are unavailable, return the execution prompt in a copyable block. Do not pretend a handoff occurred.
-
-Products and Skills describe capabilities. They do not grant permission to spend money, purchase, publish, deploy, contact people, fabricate, operate hardware, or perform another external action.
-
-## Author a completed Outcome
-
-When the user wants to publish completed work, inspect the real result and preserve the exact prompt and provenance. Create one folder:
-
-```text
-outcomes.json
-outcomes/<slug>/
-  outcome.json
-  outcome.md
-  prompt.md
-  media/        optional
-  artifacts/    optional
-  inputs/       optional
-```
-
-`outcomes.json` is the repository-root publisher index and is created or updated by the CLI. `outcome.md` is the canonical human page: one H1 title, one clear opening summary, and useful formatted explanation. `prompt.md` is the exact reusable execution prompt. `outcome.json` contains machine metadata only: author, authored timestamp, models and agents, required inputs, Products, Skills with last-reviewed commits, and media or artifact references.
-
-Do not reconstruct absent provenance as fact. Mark unknown values honestly. Products and models belong in `outcome.json`; deliverables and detailed work instructions belong in `prompt.md`; result explanation belongs in `outcome.md`.
-
-Use the CLI to scaffold and validate:
-
-```text
-npx @fraylabs/possible@0.2.0 create <slug>
-npx @fraylabs/possible@0.2.0 validate [directory]
-```
-
-## Publish from the owner's source
-
-Possible does not host publisher accounts or own the canonical files. A publisher exposes Outcomes from either:
-
-- a public GitHub repository; or
-- `https://publisher.example/.well-known/possible/outcomes.json`.
-
-The publisher index is a thin list of manifest locations. Possible snapshots the public source revision and displays it; changing the source creates a new revision rather than rewriting history.
-
-```text
-npx @fraylabs/possible@0.2.0 publish [owner/repository | https://publisher.example]
-npx @fraylabs/possible@0.2.0 add <owner/repository | https://publisher.example>
-npx @fraylabs/possible@0.2.0 use <source>@<slug>
-```
-
-GitHub publishing requires a clean committed revision so the snapshot is reproducible. No Possible login is required. A publisher-domain source is Official for that domain; other sources are Community unless their ownership follows directly from the public source.
-
-## Local bookmarks
-
-Use bookmarks only when the user asks:
-
-```text
-npx @fraylabs/possible@0.2.0 bookmark add <outcome-slug>
-npx @fraylabs/possible@0.2.0 bookmark list
-npx @fraylabs/possible@0.2.0 bookmark remove <outcome-slug>
-```
-
-Bookmarks are stored locally in `.possible` and do not require an account.

package/assets/possible/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Possible"
-  short_description: "Discover Outcomes and prepare complete prompts"
-  default_prompt: "Use $possible to find relevant Outcomes and turn my request into a complete execution prompt for a fresh agent."

package/src/init.mjs

@@ -1,150 +0,0 @@
-import { constants } from "node:fs";
-import { copyFile, lstat, mkdir, readFile, readdir } from "node:fs/promises";
-import { isAbsolute, join, relative, resolve, sep } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const DEFAULT_SOURCE = fileURLToPath(new URL("../assets/possible", import.meta.url));
-const INSTALL_SEGMENTS = [".agents", "skills", "possible"];
-
-export class InstallConflictError extends Error {
-  constructor(conflicts) {
-    super(
-      `Possible was not installed because existing files conflict:\n${conflicts
-        .map((path) => `  - ${path}`)
-        .join("\n")}\nMove or remove the conflicting path, then run the command again.`,
-    );
-    this.name = "InstallConflictError";
-    this.conflicts = conflicts;
-  }
-}
-
-const pathExists = async (path) => {
-  try {
-    return await lstat(path);
-  } catch (error) {
-    if (error?.code === "ENOENT") return null;
-    throw error;
-  }
-};
-
-const listTree = async (root, current = "") => {
-  const directory = join(root, current);
-  const entries = await readdir(directory, { withFileTypes: true });
-  const files = [];
-  const directories = [];
-
-  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
-    const child = join(current, entry.name);
-    if (entry.isSymbolicLink()) {
-      throw new Error(`The packaged Possible skill contains an unsupported symbolic link: ${child}`);
-    }
-    if (entry.isDirectory()) {
-      directories.push(child);
-      const nested = await listTree(root, child);
-      directories.push(...nested.directories);
-      files.push(...nested.files);
-      continue;
-    }
-    if (!entry.isFile()) {
-      throw new Error(`The packaged Possible skill contains an unsupported entry: ${child}`);
-    }
-    files.push(child);
-  }
-
-  return { directories, files };
-};
-
-const sameFile = async (left, right) => {
-  const [leftContent, rightContent] = await Promise.all([readFile(left), readFile(right)]);
-  return leftContent.equals(rightContent);
-};
-
-const displayPath = (projectRoot, path) => relative(projectRoot, path) || ".";
-
-const assertInsideProject = (projectRoot, path) => {
-  const rel = relative(projectRoot, path);
-  if (rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel)) return;
-  throw new Error(`Refusing to write outside the target project: ${path}`);
-};
-
-const ensureDirectory = async (projectRoot, path) => {
-  assertInsideProject(projectRoot, path);
-  try {
-    await mkdir(path);
-  } catch (error) {
-    if (error?.code !== "EEXIST") throw error;
-  }
-  const stats = await lstat(path);
-  if (!stats.isDirectory() || stats.isSymbolicLink()) {
-    throw new InstallConflictError([displayPath(projectRoot, path)]);
-  }
-};
-
-export async function installPossibleSkill({ projectDirectory = process.cwd(), sourceDirectory = DEFAULT_SOURCE } = {}) {
-  const projectRoot = resolve(projectDirectory);
-  const projectStats = await pathExists(projectRoot);
-  if (!projectStats?.isDirectory()) {
-    throw new Error(`Target project is not a directory: ${projectRoot}`);
-  }
-
-  const sourceRoot = resolve(sourceDirectory);
-  const sourceStats = await pathExists(sourceRoot);
-  if (!sourceStats?.isDirectory()) {
-    throw new Error(`Packaged Possible skill is missing: ${sourceRoot}`);
-  }
-
-  const tree = await listTree(sourceRoot);
-  const installRoot = join(projectRoot, ...INSTALL_SEGMENTS);
-  const directoryPaths = [
-    join(projectRoot, INSTALL_SEGMENTS[0]),
-    join(projectRoot, ...INSTALL_SEGMENTS.slice(0, 2)),
-    installRoot,
-    ...tree.directories.map((path) => join(installRoot, path)),
-  ];
-  const conflicts = [];
-
-  for (const path of directoryPaths) {
-    assertInsideProject(projectRoot, path);
-    const stats = await pathExists(path);
-    if (stats && (!stats.isDirectory() || stats.isSymbolicLink())) {
-      conflicts.push(displayPath(projectRoot, path));
-    }
-  }
-
-  const missingFiles = [];
-  for (const sourceRelativePath of tree.files) {
-    const sourcePath = join(sourceRoot, sourceRelativePath);
-    const destinationPath = join(installRoot, sourceRelativePath);
-    assertInsideProject(projectRoot, destinationPath);
-    const stats = await pathExists(destinationPath);
-    if (!stats) {
-      missingFiles.push({ sourcePath, destinationPath });
-    } else if (!stats.isFile() || stats.isSymbolicLink() || !(await sameFile(sourcePath, destinationPath))) {
-      conflicts.push(displayPath(projectRoot, destinationPath));
-    }
-  }
-
-  if (conflicts.length > 0) {
-    throw new InstallConflictError([...new Set(conflicts)].sort());
-  }
-
-  for (const path of directoryPaths) {
-    await ensureDirectory(projectRoot, path);
-  }
-  for (const { sourcePath, destinationPath } of missingFiles) {
-    try {
-      await copyFile(sourcePath, destinationPath, constants.COPYFILE_EXCL);
-    } catch (error) {
-      if (error?.code === "EEXIST") {
-        throw new InstallConflictError([displayPath(projectRoot, destinationPath)]);
-      }
-      throw error;
-    }
-  }
-
-  return {
-    changed: missingFiles.length > 0,
-    filesWritten: missingFiles.length,
-    installPath: displayPath(projectRoot, installRoot),
-  };
-}