failproofai 1.0.2-beta.7 → 1.0.2-beta.8

package/src/hooks/pack-manifest.ts

@@ -54,6 +54,24 @@ const SHA256_RE = /^[a-f0-9]{64}$/;
 export const PACK_ID_RE = /^[A-Za-z0-9._-]{1,64}\/[A-Za-z0-9._-]{1,64}$/;
 /** A version string, kept loose enough for semver and a tag. */
 export const PACK_VERSION_RE = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/;
+/**
+ * The git commit a pack was built from — PROVENANCE, and deliberately not the
+ * same thing as `sha256`.
+ *
+ * `sha256` is the digest of the entry artifact: the security pin, re-verified
+ * before every import, and the reason a pack cannot change under a machine
+ * after it was installed. This answers a different question — WHICH SOURCE
+ * produced that artifact — which no digest can, because the digest is of the
+ * bundled output and the output names no input.
+ *
+ * Always optional. A pack published from a directory that is not a git checkout
+ * has no commit, and that is a supported way to publish, so every surface that
+ * reads this must render its absence rather than treat it as a defect.
+ *
+ * Abbreviated forms are accepted from 7 characters, which is what `git log`
+ * prints and therefore what somebody copying one will have.
+ */
+export const PACK_COMMIT_RE = /^[0-9a-f]{7,40}$/;
 /**
  * A pack policy's own name. `/` is REFUSED, and that is the important character:
  * `normalizePolicyName` passes any name containing one straight through, and
@@ -72,6 +90,8 @@ export interface InstalledPackRecord {
   /** Path to the single entry artifact, relative to `packsDir()`. */
   entry: string;
   sha256: string;
+  /** The git commit this pack was built from, when its publisher had one. */
+  commit?: string;
   effect?: string;
   policies?: unknown;
   /**
@@ -106,6 +126,8 @@ export interface ResolvedPack {
   /** Absolute, real, verified-to-be-inside-the-root path to the entry module. */
   path: string;
   sha256: string;
+  /** The git commit this pack was built from, when its publisher had one. */
+  commit?: string;
   effect: PolicyEffect;
   /** The pack's own catalog, in declared order. */
   policies: PolicyCatalogEntry[];
@@ -152,7 +174,8 @@ export function parsePackIdentity(value: {
   id?: unknown;
   version?: unknown;
   effect?: unknown;
-}): { id: string; version: string; effect: PolicyEffect } {
+  commit?: unknown;
+}): { id: string; version: string; effect: PolicyEffect; commit?: string } {
   if (typeof value.id !== "string" || !PACK_ID_RE.test(value.id)) {
     throw new Error(`unsafe pack id ${JSON.stringify(value.id)}`);
   }
@@ -162,10 +185,20 @@ export function parsePackIdentity(value: {
   if (value.effect !== undefined && value.effect !== "enforce" && value.effect !== "observe") {
     throw new Error(`unknown effect ${JSON.stringify(value.effect)} for pack ${value.id}`);
   }
+  // Malformed provenance is DROPPED, never fatal. It is a label on the artifact,
+  // not part of what makes it safe to run — so a publisher who wrote something
+  // odd here gets a pack that installs and simply says nothing about its
+  // origin, rather than a pack nobody can install. The digest still decides
+  // whether the bytes are the ones that were published.
+  const commit =
+    typeof value.commit === "string" && PACK_COMMIT_RE.test(value.commit.trim().toLowerCase())
+      ? value.commit.trim().toLowerCase()
+      : undefined;
   return {
     id: value.id,
     version: value.version,
     effect: (value.effect as PolicyEffect | undefined) ?? "enforce",
+    ...(commit ? { commit } : {}),
   };
 }
 

package/src/hooks/pack-store.ts

@@ -17,11 +17,16 @@
  *
  * Asset URLs are CONSTRUCTED from an owner, repo and concrete tag. When the
  * user omits a tag, one `releases/latest` redirect resolves it before any asset
- * is fetched or written. There is no API lookup or rate-limit dependency, and
- * the installed record always names the pinned result — which has to AGREE with
- * the version that pack's manifest declares, or nothing is installed at all
+ * is fetched or written. There is no index to poison, and the installed record
+ * always names the pinned result — which has to AGREE with the version that
+ * pack's manifest declares, or nothing is installed at all
  * (`packTagMatchesVersion`).
  *
+ * `resolveTagForCommit` is the ONE exception, and it is opt-in: typing
+ * `owner/repo@a1b2c3d` asks a question no URL can answer, so that path — and no
+ * other — reads the releases API. It chooses WHICH release; every verification
+ * below runs on the result exactly as it would on a typed tag.
+ *
  * ## Never on the hook path
  *
  * Everything here touches the network. A hook must never wait on it. This module
@@ -30,7 +35,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { packsRoot, parsePackIdentity, parsePackPolicy, readInstalledPacks } from "./pack-manifest";
+import { PACK_COMMIT_RE, packsRoot, parsePackIdentity, parsePackPolicy, readInstalledPacks } from "./pack-manifest";
 import type { ResolvedPack } from "./pack-manifest";
 import type { InstalledPackRecord } from "./pack-manifest";
 import type { PolicyCatalogEntry } from "./policy-types";
@@ -210,6 +215,132 @@ export async function resolveLatestTag(spec: PackSpec): Promise<string> {
   return tag;
 }
 
+/**
+ * The GitHub API, for the ONE lookup on this whole path that needs one.
+ *
+ * Read per call rather than captured at import, the way `baseUrl()` above is:
+ * the value has to be settable by a test that points it at a local server, and
+ * a module-level const would freeze whatever the environment happened to hold
+ * when this file was first imported.
+ */
+function githubApiBase(): string {
+  return (process.env.FAILPROOFAI_GITHUB_API ?? "https://api.github.com").replace(/\/+$/, "");
+}
+
+/**
+ * The release tag published from a given git commit, or null when no release
+ * claims it.
+ *
+ * ## Why this is the only API call in the install path
+ *
+ * Everything else here CONSTRUCTS its URLs from owner, repo and tag and
+ * discovers nothing — that is what leaves no index to poison, and it must stay
+ * true for everybody who did not opt in. A commit is the one spelling that
+ * cannot be turned into a URL, because the mapping from commit to tag exists
+ * only on the server. So this runs when, and only when, the user typed a hex
+ * string after the `@` themselves.
+ *
+ * ## What the answer is allowed to decide
+ *
+ * WHICH release, and nothing else. The release body is publisher-controlled
+ * text on somebody else's repository and can say anything, so it selects a tag
+ * and then every downstream check — SHA256SUMS, the digest pin recorded in
+ * `installed.json`, `packTagMatchesVersion` — runs exactly as it would for a
+ * typed tag. A body that lies picks the wrong release; it cannot make an
+ * unverified artifact install.
+ *
+ * ## Ambiguity is a refusal, not a guess
+ *
+ * A 7-character prefix colliding across two releases is precisely why git
+ * itself refuses to resolve one, and picking either would install code the user
+ * did not ask for while reporting success. The matching tags and their full
+ * commits go in the message so the next command can be typed from it.
+ */
+export async function resolveTagForCommit(spec: PackSpec, commit: string): Promise<string | null> {
+  const prefix = commit.toLowerCase();
+  const url = `${githubApiBase()}/repos/${spec.owner}/${spec.repo}/releases?per_page=100`;
+  let payload: unknown;
+  try {
+    // No credential is required — a pack has to be public to install at all,
+    // since installs are anonymous HTTPS. A token is taken when one happens to
+    // be in the environment purely for the rate limit (60/hour → 5000).
+    const token = (process.env.GITHUB_TOKEN || process.env.GH_TOKEN || "").trim();
+    const response = await fetch(url, {
+      headers: {
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        Accept: "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+        "User-Agent": "failproofai",
+      },
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      redirect: "follow",
+    });
+    if (!response.ok) throw new Error(`GET ${url} returned ${response.status}`);
+    payload = await response.json();
+  } catch (err) {
+    // Deliberately NOT a fall-through to "treat it as a literal tag". A lookup
+    // that could not run has established nothing — the fall-through would then
+    // 404 on an asset URL built from a commit, and report a missing SHA256SUMS
+    // for a release nobody ever claimed existed. Name the thing that failed.
+    throw new Error(
+      `could not resolve commit ${commit} in ${spec.owner}/${spec.repo}: ${errText(err)}. ` +
+        `Name the release tag instead if you know it.`,
+    );
+  }
+
+  // Imported here rather than at the top of the file: `pack-cli` imports this
+  // module, so a static import would close a cycle for the sake of one format
+  // reader. The reader has to be the SAME one `publish` writes with, or the two
+  // drift silently and a listing and an install disagree about the same body.
+  const { parseReleaseBody } = await import("./pack-cli");
+  const releases = Array.isArray(payload)
+    ? (payload as Array<{ tag_name?: unknown; body?: unknown }>)
+    : [];
+  const matches: Array<{ tag: string; commit: string }> = [];
+  for (const release of releases) {
+    const tag = typeof release.tag_name === "string" ? release.tag_name : "";
+    // A tag from the API becomes part of an asset URL, so it passes the same
+    // check a typed one does rather than being trusted for having come back
+    // over HTTPS.
+    if (!tag || !TAG_RE.test(tag)) continue;
+    const facts = parseReleaseBody(typeof release.body === "string" ? release.body : "");
+    // The typed string is a PREFIX of the recorded commit, which is the
+    // direction git works in and therefore the one a person copying out of
+    // `git log` will have.
+    if (facts.commit && facts.commit.startsWith(prefix)) matches.push({ tag, commit: facts.commit });
+  }
+
+  if (matches.length > 1) {
+    throw new Error(
+      `commit ${commit} matches ${matches.length} releases of ${spec.owner}/${spec.repo}: ` +
+        matches.map((m) => `${m.tag} (${m.commit})`).join(", ") +
+        `. Name one of those tags, or type more of the commit.`,
+    );
+  }
+  return matches.length === 1 ? matches[0].tag : null;
+}
+
+/**
+ * The concrete tag to install, from whatever the user typed after the `@`.
+ *
+ * Three shapes, in the order they are tried:
+ *
+ *  - nothing — resolved from `releases/latest`, as it always was;
+ *  - a hex string — looked up as a COMMIT first, because typing one is how a
+ *    person asks for that; and
+ *  - anything else — taken literally.
+ *
+ * A hex string that matches no release falls back to being a literal tag. A
+ * repository may genuinely have a tag named `abc1234`, and refusing to install
+ * a tag that exists because it also looks like a commit would be a regression
+ * for somebody who never asked for commit resolution at all.
+ */
+export async function resolveSpecTag(parsed: PackSpec): Promise<string> {
+  if (parsed.tag === null) return resolveLatestTag(parsed);
+  if (!PACK_COMMIT_RE.test(parsed.tag)) return parsed.tag;
+  return (await resolveTagForCommit(parsed, parsed.tag)) ?? parsed.tag;
+}
+
 /**
  * The canonical spelling recorded in `installed.json`.
  *
@@ -324,6 +455,8 @@ interface FetchedPack {
   version: string;
   policies: PolicyCatalogEntry[];
   effect?: PolicyEffect;
+  /** The git commit the publisher built this from, when they had one. */
+  commit?: string;
   artifact: Buffer;
   artifactDigest: string;
 }
@@ -350,6 +483,18 @@ export interface PackAddOptions {
   only?: string[];
   categories?: string[];
   all?: boolean;
+  /**
+   * Add to what is already on, rather than replacing it.
+   *
+   * Set by the CLI FLAGS (`--policy`, `--category`) and deliberately NOT by the
+   * interactive picker: the picker's list is the complete answer — unticking
+   * everything means enable none — while a flag on an already-installed pack
+   * means "also turn these on". Without the distinction, following the pack
+   * README's own path (take the defaults, then add a category) silently
+   * switched the defaults off. No effect on a first install, where there is
+   * nothing to merge with.
+   */
+  merge?: boolean;
   /** Agent CLIs this pack should guard. Omitted means all of them. */
   clis?: string[];
 }
@@ -395,6 +540,8 @@ export interface PackPreview {
   id: string;
   version: string;
   effect: PolicyEffect;
+  /** The git commit the publisher built this from, when they had one. */
+  commit?: string;
   policies: PolicyCatalogEntry[];
   /** The exact source the preview was read from, tag resolved and pinned. */
   source: string;
@@ -421,10 +568,7 @@ export async function fetchPackPreview(source: string): Promise<PackPreview> {
   }
   const parsed = parsePackSpec(source);
   const resolvedFromLatest = parsed.tag === null;
-  const spec: PinnedPackSpec =
-    parsed.tag !== null
-      ? { ...parsed, tag: parsed.tag }
-      : { ...parsed, tag: await resolveLatestTag(parsed) };
+  const spec: PinnedPackSpec = { ...parsed, tag: await resolveSpecTag(parsed) };
 
   const checksums = (await fetchBytes(packAssetUrl(spec, PACK_CHECKSUMS_ASSET))).toString("utf8");
   const manifestBytes = await fetchBytes(packAssetUrl(spec, PACK_MANIFEST_ASSET));
@@ -443,7 +587,9 @@ export async function fetchPackPreview(source: string): Promise<PackPreview> {
     throw new Error(`${PACK_MANIFEST_ASSET} is not valid JSON: ${errText(err)}`);
   }
   if (!raw || typeof raw !== "object") throw new Error(`${PACK_MANIFEST_ASSET} is not an object`);
-  const value = raw as { id?: unknown; version?: unknown; policies?: unknown; effect?: unknown };
+  const value = raw as {
+    id?: unknown; version?: unknown; policies?: unknown; effect?: unknown; commit?: unknown;
+  };
   const identity = parsePackIdentity(value);
   if (!Array.isArray(value.policies) || value.policies.length === 0) {
     throw new Error("pack manifest declares no policies");
@@ -452,6 +598,7 @@ export async function fetchPackPreview(source: string): Promise<PackPreview> {
     id: identity.id,
     version: identity.version,
     effect: identity.effect,
+    ...(identity.commit ? { commit: identity.commit } : {}),
     policies: value.policies.map((policy, i) => parsePackPolicy(identity.id, policy, i)),
     source: formatPackSpec(spec),
     resolvedFromLatest,
@@ -498,7 +645,9 @@ async function fetchPack(spec: PinnedPackSpec): Promise<FetchedPack> {
     throw new Error(`${PACK_MANIFEST_ASSET} is not valid JSON: ${errText(err)}`);
   }
   if (!parsed || typeof parsed !== "object") throw new Error(`${PACK_MANIFEST_ASSET} is not an object`);
-  const raw = parsed as { id?: unknown; version?: unknown; policies?: unknown; effect?: unknown };
+  const raw = parsed as {
+    id?: unknown; version?: unknown; policies?: unknown; effect?: unknown; commit?: unknown;
+  };
   const identity = parsePackIdentity(raw);
   if (!Array.isArray(raw.policies) || raw.policies.length === 0) {
     throw new Error("pack manifest declares no policies");
@@ -513,6 +662,7 @@ async function fetchPack(spec: PinnedPackSpec): Promise<FetchedPack> {
     version: identity.version,
     policies,
     ...(raw.effect !== undefined ? { effect: identity.effect } : {}),
+    ...(identity.commit ? { commit: identity.commit } : {}),
     artifact,
     artifactDigest,
   };
@@ -542,7 +692,9 @@ export function slugifyCategory(category: string): string {
  */
 function resolveSelection(
   policies: PolicyCatalogEntry[],
-  opts: { only?: string[]; categories?: string[]; all?: boolean } | undefined,
+  opts:
+    | { only?: string[]; categories?: string[]; all?: boolean; merge?: boolean }
+    | undefined,
   previous: string[] | null | undefined,
   previouslyInstalled: boolean,
 ): { enabled: string[] | null; reason: SelectionReason } {
@@ -578,8 +730,29 @@ function resolveSelection(
   // opposite of what was chosen, reported as "the pack's defaults". Presence of
   // the key is the signal, not its length.
   if (opts?.only !== undefined || opts?.categories?.length) {
+    // `merge` separates the two callers that both arrive here with a list.
+    //
+    // The PICKER's list is the complete answer: what is ticked is what should
+    // be on, and unticking everything means enable none — which is why an
+    // expressed selection replaces at all, and must keep replacing.
+    //
+    // A FLAG is an addition. `policies add <pack> --category Git` on a pack
+    // that is already installed means "also turn Git on", and replacing there
+    // switched off everything the user had. Following the pack README's own
+    // path — take the defaults, then add a category — left them with SIX
+    // policies on where they had started with ten, silently, from a command
+    // whose first word is `add`.
+    //
     // Kept in the pack's declared order, which is the order everything else
     // presents them in.
+    if (opts.merge && previouslyInstalled) {
+      // Already the whole catalog. Adding to everything is everything, and
+      // `null` is how "the whole pack" is recorded — materialising it into a
+      // list here would freeze out any policy a later version adds.
+      if (previous === null) return { enabled: null, reason: "carried" };
+      for (const name of previous ?? []) picked.add(name);
+      return { enabled: available.filter((n) => picked.has(n)), reason: "added" };
+    }
     return { enabled: available.filter((n) => picked.has(n)), reason: "selected" };
   }
 
@@ -592,7 +765,7 @@ function resolveSelection(
   return { enabled: policies.filter((p) => p.defaultEnabled).map((p) => p.name), reason: "defaults" };
 }
 
-export type SelectionReason = "all" | "selected" | "carried" | "defaults";
+export type SelectionReason = "all" | "selected" | "carried" | "defaults" | "added";
 
 /**
  * Import the artifact and check it registers what the manifest promised.
@@ -669,9 +842,7 @@ export async function addPack(
   // Resolve BEFORE anything is written, and pin the concrete result. A tagless
   // source is a convenience for the person typing; what the machine records must
   // always name one release.
-  const spec: PinnedPackSpec = parsed.tag
-    ? { ...parsed, tag: parsed.tag }
-    : { ...parsed, tag: await resolveLatestTag(parsed) };
+  const spec: PinnedPackSpec = { ...parsed, tag: await resolveSpecTag(parsed) };
   const resolvedFromLatest = parsed.tag === null;
   const fetched = await fetchPack(spec);
   // Checked here, before a byte is written and before the artifact is imported,
@@ -753,13 +924,34 @@ export async function addPack(
     entry: artifactRel,
     sha256: fetched.artifactDigest,
     policies: fetched.policies,
+    // Provenance, carried through from the manifest so `policies` and the
+    // dashboard can say which source produced what is installed. NOT part of
+    // verification — `sha256` above is the pin, and this is a label beside it.
+    ...(fetched.commit ? { commit: fetched.commit } : {}),
     ...(fetched.effect ? { effect: fetched.effect } : {}),
     ...(enabled ? { enabled } : {}),
     // Omitted, not written as the full list, when the user did not narrow it.
     // An absent `clis` means "every agent", and it keeps meaning that when a
     // thirteenth CLI is supported — whereas a materialised list of twelve would
     // silently exclude the new one from every pack installed before it existed.
-    ...(opts?.clis ? { clis: opts.clis } : {}),
+    //
+    // A prior narrowing is CARRIED when this caller named none, for the same
+    // reason `enabled` is: `upsertInstalled` replaces the row wholesale, so
+    // writing nothing here threw the user's scope away. A pack scoped to Claude
+    // silently started guarding all eleven agents on the next `policies add` —
+    // the same shape as the bug `merge` fixes, in the widening direction, which
+    // is the worse one: it over-enforces, on agents nobody chose.
+    //
+    // `merge === false` is the ONE caller this must not do it for. The picker
+    // says "every agent" by leaving `clis` absent (pack-cli.ts, where a full
+    // tick deliberately writes nothing) — so for it, absent is an ANSWER, and
+    // carrying a prior narrowing would make widening back to all impossible.
+    // Everywhere else absent means no opinion was expressed.
+    ...(opts?.clis
+      ? { clis: opts.clis }
+      : opts?.merge !== false && prior?.clis
+        ? { clis: prior.clis }
+        : {}),
   };
 
   const absorbed = upsertInstalled(record);

package/src/hooks/tui.ts

@@ -108,6 +108,8 @@ const RADIO_OFF = "○";
 export const CHECK_ON = "◼";
 export const CHECK_OFF = "◻";
 export const CARET = "❯";
+/** The return key, as the multi-select hints already spell it. */
+export const CARET_RETURN = "↵";
 const MARK = "\u25AE\u25AE"; // ▮▮ — the brand mark, per the design system
 
 // ── color ─────────────────────────────────────────────────────────────────
@@ -933,6 +935,24 @@ export function promptText(opts: PromptTextOptions): Promise<string | null> {
     });
   }
 
+  // A default nobody can see is a default nobody uses.
+  //
+  // `defaultValue` is applied on an empty submit and is otherwise INVISIBLE, so
+  // every prompt carrying one had to remember to spell it into its own hint —
+  // and the one where it mattered most, "Where should this publish?", spelled
+  // out the value while never saying that return was the key that took it.
+  // Somebody looking at a prefilled-looking placeholder types the whole thing
+  // out again. Owned here so a prompt cannot be added without it.
+  //
+  // Never for a masked prompt: those hold credentials, and the entire reason
+  // the characters are hidden is that the screen is being shared or recorded.
+  const hintText = [
+    opts.defaultValue && !opts.mask ? `${CARET_RETURN} ${opts.defaultValue}` : "",
+    opts.hint ?? "",
+  ]
+    .filter(Boolean)
+    .join("  ·  ");
+
   return new Promise((resolve) => {
     let value = "";
     const draw = (error?: string) => {
@@ -942,7 +962,7 @@ export function promptText(opts: PromptTextOptions): Promise<string | null> {
       // steps aside as soon as there is a real answer to look at. Keeping both
       // on one line put the example and the input side by side, which is the
       // arrangement most likely to make somebody wonder which one is theirs.
-      const hint = opts.hint && value.length === 0 ? `  ${c.dim(opts.hint)}` : "";
+      const hint = hintText && value.length === 0 ? `  ${c.dim(hintText)}` : "";
       // Truncate to ONE physical row. `\r\x1b[2K` erases the row the cursor is
       // on and nothing above it — so a line wider than the terminal wraps, the
       // erase reaches only its last row, and every keystroke leaves the earlier