failproofai 1.0.6-beta.1 → 1.0.7-beta.0

package/src/hooks/loader-utils.ts

@@ -191,7 +191,13 @@ export async function createEsmShim(
   const shimCode = [
     `import _cjs from '${distUrl}';`,
     `export const customPolicies = _cjs.customPolicies;`,
+    // Every name a policy file may import has to be listed HERE as well as in
+    // `src/index.ts`: this shim is an ESM module, so importing a name it does not
+    // declare is a link-time error, not an undefined at runtime. A pack entry
+    // calling `semanticPolicies.add` would fail to load entirely.
+    `export const semanticPolicies = _cjs.semanticPolicies;`,
     `export const getCustomHooks = _cjs.getCustomHooks;`,
+    `export const getSemanticRegistrations = _cjs.getSemanticRegistrations;`,
     `export const clearCustomHooks = _cjs.clearCustomHooks;`,
     `export const allow = _cjs.allow;`,
     `export const deny = _cjs.deny;`,

package/src/hooks/manager.ts

@@ -29,7 +29,7 @@ import { CORE_SOURCE, addPack, setPackPolicyEnabled } from "./pack-store";
 import type { ResolvedPack } from "./pack-manifest";
 import { hasInstalledPacks, readInstalledPacks } from "./pack-manifest";
 import { packPolicyParamKey } from "./policy-evaluator";
-import { probeDaemonEndToEnd } from "./daemon-service";
+import { probeDaemonPolicyEvaluation } from "./daemon-service";
 import {
   chip,
   note,
@@ -477,12 +477,12 @@ async function installHooksImpl(
   const daemonRequiredBy = selectedIntegrations
     .map(({ integration }) => integration)
     .filter((integration) => integration.requiresHealthyDaemon);
-  if (daemonRequiredBy.length > 0 && !(await probeDaemonEndToEnd())) {
+  if (daemonRequiredBy.length > 0 && !(await probeDaemonPolicyEvaluation())) {
     const names = daemonRequiredBy.map((integration) => integration.displayName).join(", ");
     const verb = daemonRequiredBy.length === 1 ? "requires" : "require";
     throw new CliError(
-      `${names} ${verb} a healthy failproofaid daemon before FailproofAI enforcement can be enabled.\n` +
-        "Run `failproofai config` to install and configure the daemon, then retry.",
+      `${names} ${verb} a compatible failproofaid daemon with native policy evaluation before FailproofAI enforcement can be enabled.\n` +
+        "Run `failproofai config` to install or update the daemon, then retry.",
     );
   }
 

package/src/hooks/pack-cli.ts

@@ -13,7 +13,20 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "nod
 import { INTEGRATION_TYPES } from "./types";
 import { PACK_COMMIT_RE, PACK_VERSION_RE } from "./pack-manifest";
 import { detectInstalledClis } from "./integrations";
-import { parsePackIdentity, parsePackPolicy, readInstalledPacks } from "./pack-manifest";
+import {
+  packParamsProblem,
+  parsePackIdentity,
+  parsePackPolicy,
+  parsePackSemanticPolicy,
+  readInstalledPacks,
+  type SemanticManifestEntry,
+} from "./pack-manifest";
+import { parseSemver } from "./semver-precedence";
+// The build step measures a pack's question set against the envelope's own
+// budget, which means reaching the semantic side. This is a CLI module — loaded
+// by `failproofai publish`, never by a hook — so the rule that keeps those
+// modules off an unconfigured machine's hook path does not apply here.
+import { MAX_PACK_QUESTION_CHARS, questionChars } from "./semantic/pack-policies";
 import {
   AmbiguousPackId,
   PACK_CHECKSUMS_ASSET,
@@ -30,6 +43,9 @@ import {
 } from "./pack-store";
 import type { PolicyEffect } from "./cloud-managed-policies";
 import { loadCustomHooks } from "./custom-hooks-loader";
+import { getSemanticRegistrations } from "./custom-hooks-registry";
+import { authorityFieldsOf, authorityProblem } from "./policy-authority";
+import type { SemanticPolicyDeclaration } from "./policy-types";
 import type { MultiChoice, TTYIn, TTYOut } from "./tui";
 import {
   chip,
@@ -294,12 +310,23 @@ async function build(rest: string[]): Promise<PackCliResult> {
   const version = flag("version");
   const commit = flag("commit");
   const effect = flag("effect") ?? "enforce";
+  const minCliVersion = flag("min-cli-version");
   const outDir = resolve(flag("out") ?? "dist-pack");
 
   if (!entry || !id || !version) {
     return fail([
       "Usage: failproofai publish <entry.mjs> --repo <owner>/<repo> --version <version>",
-      "       [--out <dir>] [--effect enforce|observe]",
+      "       [--out <dir>] [--effect enforce|observe] [--min-cli-version <version>]",
+    ]);
+  }
+  // Refused here rather than written and refused by every machine that installs
+  // it. A `minCliVersion` nobody can order is a requirement nobody can check,
+  // and the loader treats one as grounds to refuse the whole pack — so a typo
+  // published here is a pack that installs nowhere.
+  if (minCliVersion !== undefined && parseSemver(minCliVersion) === null) {
+    return fail([
+      `--min-cli-version ${JSON.stringify(minCliVersion)} is not a version that can be compared.`,
+      "It must be plain semver — 1.0.7, or 1.0.7-beta.0 for a pre-release.",
     ]);
   }
   let identity: { id: string; version: string; effect: PolicyEffect; commit?: string };
@@ -324,15 +351,25 @@ async function build(rest: string[]): Promise<PackCliResult> {
   }
 
   let hooks;
+  let semanticDeclarations: SemanticPolicyDeclaration[];
   try {
     hooks = await loadCustomHooks(entryPath, { strict: true });
+    // Read AFTER the load, from the same registration pass `clearCustomHooks`
+    // resets: a semantic policy has no `fn`, so it never travels back through
+    // `loadCustomHooks`'s return value.
+    semanticDeclarations = [...getSemanticRegistrations()];
   } catch (err) {
     return fail([`Could not load ${entryPath}: ${err instanceof Error ? err.message : String(err)}`]);
   }
-  if (hooks.length === 0) {
+  // BOTH registries, or a pack that ships only Jev questions — a legitimate
+  // thing to publish, since the regex floor may already be somebody else's pack
+  // — is refused for registering nothing.
+  if (hooks.length === 0 && semanticDeclarations.length === 0) {
     return fail([
       `${entryPath} registered no policies.`,
-      "A pack entry calls customPolicies.add({ name, description, match, fn }) for each one.",
+      "A pack entry calls customPolicies.add({ name, description, match, fn }) for each one,",
+      "and semanticPolicies.add({ name, title, appliesTo, mode, userCanOverride, probes, guidance })",
+      "for each Jev question set.",
     ]);
   }
 
@@ -359,6 +396,66 @@ async function build(rest: string[]): Promise<PackCliResult> {
     ]);
   }
 
+  // The pack's Jev question sets, validated with the LOADER's own rules — the
+  // same deal `parsePackPolicy` gets above, so a semantic policy that could
+  // never load fails here, where the author can fix it.
+  const semantic: SemanticManifestEntry[] = [];
+  for (const [index, declaration] of semanticDeclarations.entries()) {
+    try {
+      const parsed = parsePackSemanticPolicy(identity.id, declaration, index);
+      // Same reason two regex policies cannot share a name, one layer over: the
+      // answer map is keyed `<policy>.<probe>`, so a duplicate would overwrite
+      // the first policy's questions in the compiled request.
+      if (semantic.some((s) => s.name === parsed.name)) {
+        throw new Error(`two semantic policies are called ${JSON.stringify(parsed.name)}`);
+      }
+      semantic.push(parsed);
+    } catch (err) {
+      return fail([err instanceof Error ? err.message : String(err)]);
+    }
+  }
+
+  // The question budget, checked against what one Jev request can carry. A pack
+  // over it installs and then has its overflow policies dropped one by one on
+  // the user's machine, in manifest order — a pack that enforces less than it
+  // says, which is the failure this whole lane is built to avoid.
+  const questionCost = semantic.reduce((total, entry) => total + questionChars(entry), 0);
+  if (questionCost > MAX_PACK_QUESTION_CHARS) {
+    return fail([
+      `This pack's ${semantic.length} semantic policies compile to ${questionCost} characters of questions, ` +
+        `over the ${MAX_PACK_QUESTION_CHARS} one Jev request has room for.`,
+      "Shorten the probe instructions and criteria, or ship fewer policies per pack.",
+    ]);
+  }
+
+  // An authority declaration the manifest would lose, or that registration
+  // would quietly downgrade to hard, is refused HERE. Every machine that
+  // installs the pack would otherwise make the policy hard with only a warning
+  // in its own log — the author's decision, silently not taking effect — while
+  // at build time nothing is installed yet and refusing costs nobody anything.
+  // The same rule `scripts/build-policy-pack.mjs` applies to the core pack.
+  //
+  // Judged against the reviewers the PACK SHIPS WITH, not this build's: a pack
+  // that carries both tiers replaces the compiled semantic set on every machine
+  // that installs it, so `reviewedBy: ["its-own-check"]` is exactly right and
+  // the builtin list would call it a name "this build does not have". A pack
+  // with no semantic entries still answers to the builtin set, which is what its
+  // machines will be running.
+  const reviewers = semantic.length > 0 ? new Set(semantic.map((s) => s.name)) : undefined;
+  const authorityProblems = hooks.flatMap((hook) => {
+    const problem = authorityProblem({ authority: hook.authority, reviewedBy: hook.reviewedBy }, reviewers);
+    return problem ? [`  ${hook.name}: ${problem}`] : [];
+  });
+  if (authorityProblems.length > 0) {
+    return fail([
+      authorityProblems.length === 1
+        ? "One policy declares an authority this build cannot publish:"
+        : `${authorityProblems.length} policies declare an authority this build cannot publish:`,
+      ...authorityProblems,
+      'Fix the declaration, or leave authority out and the policy is "hard". See https://docs.befailproof.ai/policies/authority',
+    ]);
+  }
+
   const policies: unknown[] = [];
   for (const [index, hook] of hooks.entries()) {
     // `category` and `defaultEnabled` are pack-manifest fields a plain custom
@@ -367,13 +464,36 @@ async function build(rest: string[]): Promise<PackCliResult> {
     // FALSE: a pack's declared defaults are what `pack add` switches on with no
     // flags, and switching on a stranger's every policy unattended is the
     // installer opinion this lane already refused once.
-    const extra = hook as unknown as { category?: unknown; defaultEnabled?: unknown };
+    const extra = hook as unknown as { category?: unknown; defaultEnabled?: unknown; params?: unknown };
+    // `params` is read off the registration for the same reason, and leaving it
+    // out was not cosmetic: `registerPolicy` takes a pack policy's schema from the
+    // MANIFEST by name, so a pack published without it evaluates every one of its
+    // policies with `ctx.params = {}` — which discards the user's own configured
+    // values too, not just the defaults. Of the 38 builtins, 19 carry a schema:
+    // `prefer-package-manager` would have been inert, and `block-sudo`'s
+    // `allowPatterns`, `block-rm-rf`'s and `block-read-outside-cwd`'s `allowPaths`
+    // would all have stopped working — every one of them failing silently
+    // STRICTER, which is the direction users work around instead of reporting.
+    const paramsProblem = packParamsProblem(extra.params);
+    if (paramsProblem) {
+      return fail([
+        `${hook.name} declares a params schema this build cannot publish: ${paramsProblem}`,
+        "A machine reads the schema from the manifest, so an unusable one is a policy",
+        "that quietly runs without its parameters. Fix the declaration, or leave params out.",
+      ]);
+    }
     const candidate = {
       name: hook.name,
       description: hook.description ?? "",
       category: typeof extra.category === "string" && extra.category ? extra.category : "General",
       defaultEnabled: extra.defaultEnabled === true,
       match: hook.match ?? {},
+      ...(extra.params !== undefined ? { params: extra.params } : {}),
+      // Whether Jev may clear this policy's verdict. A pack's MANIFEST is what
+      // a machine reads it from, so a declaration left on the registration
+      // alone would be published as nothing — silently hard. Checked above, so
+      // everything declared here is shape-valid; absent stays absent.
+      ...authorityFieldsOf(hook as unknown as Record<string, unknown>),
     };
     try {
       policies.push(parsePackPolicy(identity.id, candidate, index));
@@ -386,14 +506,21 @@ async function build(rest: string[]): Promise<PackCliResult> {
   // The manifest is hashed and the hash is the pin, so every byte in here is
   // part of what a machine verifies — a field carrying "there was nothing to
   // say" earns none of that cost. Readers already treat absence as ordinary.
+  //
+  // `minCliVersion` and `semantic` follow the same rule, and for `semantic` it is
+  // load-bearing rather than tidy: an EMPTY array would still be "a pack that
+  // declares semantic entries" to a careless reader, and the replacement rule
+  // turns that into "this pack replaced the compiled-in set with nothing".
   const manifest =
     JSON.stringify(
       {
         id: identity.id,
         version: identity.version,
+        ...(minCliVersion ? { minCliVersion } : {}),
         effect: identity.effect,
         ...(identity.commit ? { commit: identity.commit } : {}),
         policies,
+        ...(semantic.length > 0 ? { semantic } : {}),
       },
       null,
       2,
@@ -413,6 +540,16 @@ async function build(rest: string[]): Promise<PackCliResult> {
   const on = policies.filter((p) => (p as { defaultEnabled?: boolean }).defaultEnabled).length;
   return ok([
     `Built ${identity.id}@${identity.version} — ${policies.length} policies, ${on} on by default.`,
+    // Said separately, and said at all, because this half replaces the compiled-in
+    // semantic set on every machine that installs the pack. An author who did not
+    // mean to ship it should find that out here.
+    ...(semantic.length > 0
+      ? [
+          `  ${semantic.length} semantic ${semantic.length === 1 ? "policy" : "policies"} for Jev ` +
+            `(${questionCost} characters of questions), replacing this build's own set where it installs.`,
+        ]
+      : []),
+    ...(minCliVersion ? [`  Requires failproofai ${minCliVersion} or newer.`] : []),
     `  ${outDir}/${PACK_MANIFEST_ASSET}`,
     `  ${outDir}/${PACK_ENTRY_ASSET}`,
     `  ${outDir}/${PACK_CHECKSUMS_ASSET}`,
@@ -999,7 +1136,13 @@ function inferTaggedVersion(entryPath: string, sources?: string[]): string | nul
  * Identified by CONTENT, not by filename. A name convention would either miss
  * `guards.mjs` or match an unrelated `policies.mjs` that configures something
  * else entirely; a file that imports `failproofai` and calls
- * `customPolicies.add` is a policy file whatever it is called.
+ * `customPolicies.add` — or `semanticPolicies.add` — is a policy file whatever
+ * it is called.
+ *
+ * Both registries count, and leaving one out was not a cosmetic gap: a file that
+ * registers only Jev questions was undiscoverable, so `failproofai publish` in
+ * its own directory reported no policy file at all rather than reaching the
+ * "registered no policies" check and explaining itself.
  *
  * Returns ALL of them. Splitting policies across files is the normal thing to
  * do past about three, and they are one pack — so several files is an answer,
@@ -1008,8 +1151,11 @@ function inferTaggedVersion(entryPath: string, sources?: string[]): string | nul
  *
  * Non-recursive on purpose. Walking the tree finds fixtures, examples and
  * anything vendored, and publishing those is the failure this avoids.
+ *
+ * Takes the directory rather than reading `process.cwd()` so the discovery rule
+ * can be tested against a real folder without a `chdir`.
  */
-function findEntry(dir: string): string[] {
+export function findEntry(dir: string): string[] {
   let names: string[];
   try {
     names = readdirSync(dir);
@@ -1025,7 +1171,10 @@ function findEntry(dir: string): string[] {
       // would be the expensive half of this scan.
       if (statSync(full).size > 512 * 1024) continue;
       const text = readFileSync(full, "utf8");
-      if (/from\s+["']failproofai["']/.test(text) && /customPolicies\s*\.\s*add\s*\(/.test(text)) {
+      if (
+        /from\s+["']failproofai["']/.test(text) &&
+        /(?:customPolicies|semanticPolicies)\s*\.\s*add\s*\(/.test(text)
+      ) {
         found.push(full);
       }
     } catch {
@@ -1727,7 +1876,7 @@ function bundleEntry(
  */
 const PUBLISH_VALUE_FLAGS = new Set([
   "--repo", "--version", "--id", "--tag", "--notes", "--out", "--effect", "--entry", "--init",
-  "--commit",
+  "--commit", "--min-cli-version",
 ]);
 function publishEntryArg(rest: string[]): string | undefined {
   const consumed = new Set<number>();
@@ -2129,6 +2278,7 @@ async function publish(rest: string[]): Promise<PackCliResult> {
     ...(provenance && !provenance.dirty ? ["--commit", provenance.sha] : []),
     ...outFlagFrom(rest),
     ...effectFlagFrom(rest),
+    ...minCliVersionFlagFrom(rest),
   ]);
   if (built.exitCode !== 0) return built;
 
@@ -2292,6 +2442,18 @@ function effectFlagFrom(rest: string[]): string[] {
   if (i === -1) return [];
   return rest[i].includes("=") ? [rest[i]] : [rest[i], rest[i + 1]];
 }
+/**
+ * Same again for `--min-cli-version`, and it has to be forwarded explicitly
+ * because `publish` hands `build` a list it assembles rather than its own
+ * `rest`. Left off, the flag parsed, validated, refused an uncomparable value —
+ * and then never reached the manifest, so the field the whole ordering
+ * constraint rests on was silently absent from the published artifact.
+ */
+function minCliVersionFlagFrom(rest: string[]): string[] {
+  const i = rest.findIndex((a) => a === "--min-cli-version" || a.startsWith("--min-cli-version="));
+  if (i === -1) return [];
+  return rest[i].includes("=") ? [rest[i]] : [rest[i], rest[i + 1]];
+}
 
 /** `failproofai publish` — exported for bin/failproofai.mjs and the tests. */
 export async function runPublishCommand(rest: string[]): Promise<PackCliResult> {
@@ -2345,11 +2507,35 @@ async function pickClis(
  * Returns null when the user cancelled, which must not be confused with an
  * empty selection: one means "install nothing", the other means "do nothing".
  */
+/**
+ * How a pack's semantic half is named to a person: "3 Jev checks", never "3
+ * semantic policies".
+ *
+ * They are not policies in the sense every other number on these screens uses —
+ * nothing switches them on or off, `--policy` cannot name one, and they do not
+ * appear in `failproofai policies`. Calling them policies would make every count
+ * beside them read as the same kind of thing.
+ */
+function semanticPhrase(count: number): string {
+  return `${count} Jev ${count === 1 ? "check" : "checks"}`;
+}
+
 async function pickFromSource(
   source: string,
   io: { stdin: TTYIn; stdout: TTYOut },
 ): Promise<string[] | null> {
   const preview = await fetchPackPreview(source);
+  // Nothing to pick. A pack of Jev questions alone has no selectable policies —
+  // its semantic set is not switchable per entry — so the picker would draw an
+  // empty list and ask a question with no answers. `[]` rather than `null`: the
+  // user cancelled nothing, there was simply nothing to choose.
+  if (preview.policies.length === 0) {
+    io.stdout.write(
+      `\n  ${preview.id}@${preview.version} carries no selectable policies` +
+        `${preview.semantic.length > 0 ? `, only ${semanticPhrase(preview.semantic.length)}` : ""}.\n\n`,
+    );
+    return [];
+  }
   const categories = [...new Set(preview.policies.map((p) => p.category))];
   const rows: MultiChoice<string>[] = [];
   for (const category of categories) {
@@ -2364,6 +2550,15 @@ async function pickFromSource(
     }
   }
   const on = preview.policies.filter((p) => p.defaultEnabled).length;
+  // Said BEFORE the list, because the list cannot say it: a pack's Jev checks are
+  // not rows here, they arrive whole, and they replace the ones this build ships.
+  // Somebody ticking boxes should know that is part of what they are agreeing to.
+  if (preview.semantic.length > 0) {
+    io.stdout.write(
+      `\n  This pack also brings ${semanticPhrase(preview.semantic.length)}, which are not selectable —\n` +
+        `  they replace the ones this build ships with. See: failproofai policies show ${source}\n\n`,
+    );
+  }
   const picked = await multiSelect<string>({
     message: `${preview.id}@${preview.version} — which of these should be on?`,
     choices: rows,
@@ -2480,9 +2675,25 @@ async function add(rest: string[]): Promise<PackCliResult> {
     // rendered as if something had gone missing.
     lines.push(
       result.enabled.length === 0
-        ? `  enabled (0/${result.available.length}, ${why}): none — the pack is installed and enforcing nothing`
+        ? // "enforcing nothing" is only true when the pack brought nothing else.
+          // A pack of Jev checks alone enforces through the semantic tier with no
+          // regex policy enabled at all, and telling that user their install does
+          // nothing is worse than saying nothing.
+          `  enabled (0/${result.available.length}, ${why}): none` +
+          (result.semantic > 0 ? "" : " — the pack is installed and enforcing nothing")
         : `  enabled (${result.enabled.length}/${result.available.length}, ${why}): ${summarise(result.enabled)}`,
     );
+    // Counted separately, and without an on/off ratio, because there is none:
+    // a pack's Jev checks arrive whole and REPLACE the ones this build ships.
+    // Silence here was the shape of the original bug — the manifest's semantic
+    // half was fetched, verified and then never written to `installed.json`, so
+    // the half somebody installed did nothing and nothing said so.
+    if (result.semantic > 0) {
+      lines.push(
+        `  ${semanticPhrase(result.semantic)} for Jev, replacing this build's own set. ` +
+          "They apply only where you configured Jev (`failproofai jev status`).",
+      );
+    }
 
     if (skipped.length > 0) {
       lines.push(`  not enabled (${skipped.length}): ${summarise(skipped)}`);
@@ -2774,7 +2985,8 @@ async function listRemote(source: string): Promise<PackCliResult> {
     stack(
       title(
         `${preview.id}@${preview.version}`,
-        `${preview.policies.length} policies · ${categories.length} categories`,
+        `${preview.policies.length} policies · ${categories.length} categories` +
+          (preview.semantic.length > 0 ? ` · ${semanticPhrase(preview.semantic.length)}` : ""),
         opts,
       ),
       note(
@@ -2782,6 +2994,20 @@ async function listRemote(source: string): Promise<PackCliResult> {
           (preview.effect === "observe" ? " This pack OBSERVES — it records and blocks nothing." : ""),
         opts,
       ),
+      // The half that is not in the table below, said in words. It is not
+      // selectable, so it has no rows; and it REPLACES this build's own question
+      // set rather than adding to it, which is the part worth knowing before
+      // installing rather than after.
+      preview.semantic.length > 0
+        ? note(
+            `It also carries ${semanticPhrase(preview.semantic.length)} — ${preview.semantic
+              .map((s) => s.name)
+              .join(", ")}. They are not selectable, they apply only where you configured Jev, and they ` +
+              "replace the checks this build ships with.",
+            opts,
+          )
+        : null,
+      preview.minCliVersion ? note(`Requires failproofai ${preview.minCliVersion} or newer.`, opts) : null,
       preview.resolvedFromLatest ? note(`Newest release: ${preview.source}`, opts) : null,
       table({ head: ["", "", ""], rows }, opts),
       nextStep(`failproofai policies add ${source}`, "Install the defaults with:", opts),