@pareto4/pp-core 1.12.0 → 1.13.0

package/pp-core/bin/lib/org-profile.cjs

@@ -48,10 +48,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HOST_FORBIDDEN_CHARS = exports.PROFILE_REJECTED_CLONE_TARGET_PATTERNS = exports.ORG_PROFILE_SEED_KEYS = exports.ORG_PROFILE_SEED_SECTION = exports.ORG_PROFILE_ALLOWLIST = exports.ORG_PROFILE_DATA_FILE = exports.ORG_PROFILE_CONFIG_KEY = void 0;
+exports.HOST_FORBIDDEN_CHARS = exports.PROFILE_REJECTED_CLONE_TARGET_PATTERNS = exports.ORG_PROFILE_SEED_KEYS = exports.ORG_PROFILE_SEED_SECTION = exports.ORG_PROFILE_ALLOWLIST = exports.TRACE_ACCEPTED_PREDICATE_MAX = exports.TRACE_ACCEPTED_PREDICATES_CAP = exports.VAULT_TRACE_ACCEPTED_PREDICATES_KEY = exports.VAULT_REQUIRED_CONFIG_KEY = exports.ORG_PROFILE_DATA_FILE = exports.ORG_PROFILE_CONFIG_KEY = void 0;
+exports.resolveGlobalPackageRootCandidates = resolveGlobalPackageRootCandidates;
+exports.globalRootCandidatesFor = globalRootCandidatesFor;
 exports.resolveOrgProfileDocument = resolveOrgProfileDocument;
 exports.resolveOrgProfile = resolveOrgProfile;
 exports.readProfileValue = readProfileValue;
+exports.resolveVaultRequired = resolveVaultRequired;
+exports.resolveAcceptedTracePredicates = resolveAcceptedTracePredicates;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 // ─── Constants ───────────────────────────────────────────────────────────────
@@ -62,10 +66,41 @@ exports.ORG_PROFILE_CONFIG_KEY = 'org.profile';
 /** The fixed filename read from the resolved package's own directory — never the
  * package's `main`/`exports` entry, and never loaded via `require` (D-08). */
 exports.ORG_PROFILE_DATA_FILE = 'org-profile.json';
+/** The dotted key naming the vault load policy, declared boolean (default
+ * false) by `capabilities/vault/capability.json`. Named once here so neither
+ * the allowlist, the value guard nor `resolveVaultRequired` restates it. */
+exports.VAULT_REQUIRED_CONFIG_KEY = 'vault.required';
 /**
- * D-06's fixed allowlist: a profile may contribute exactly these five dotted
+ * The dotted key naming the practice-trace predicate types a READER accepts
+ * besides pp-core's own (`TRACE_PREDICATE_TYPE` in src/vault-trace.cts). It
+ * exists so a project that switches engine mid-engagement can keep reading
+ * the traces its earlier engine wrote: the org profile of that engagement
+ * lists the earlier engine's predicate URI here. Writers never use it — pp-core
+ * always writes its own URI — and pp-core itself names no such URI.
+ */
+exports.VAULT_TRACE_ACCEPTED_PREDICATES_KEY = 'vault.trace.accepted_predicates';
+/** At most this many accepted predicate URIs, each at most this long. */
+exports.TRACE_ACCEPTED_PREDICATES_CAP = 8;
+exports.TRACE_ACCEPTED_PREDICATE_MAX = 200;
+/**
+ * D-06's fixed allowlist: a profile may contribute exactly these seven dotted
  * config keys. Entry order is not contractual; membership is. Anything else
  * present in a profile document is dropped with a bounded warning.
+ *
+ * FIVE COORDINATES AND ONE POLICY. The first five answer where to fetch from.
+ * `vault.required` answers whether the vault load is mandatory, so one
+ * org-profile package can turn the load gate on across a fleet without a
+ * per-repository edit. That is this list's sharpest widening: an `npm update`
+ * of the profile package can move a build gate without a review in the
+ * consuming repository. It is bounded three ways: project config outranks the
+ * profile, so any project can opt out explicitly; the profile can only raise
+ * the gate from the built-in default `false` (a gate turning on fails
+ * closed); and the value guard accepts only the two boolean literals.
+ * `vault.enabled` (arming the capability) stays off the list.
+ *
+ * `vault.trace.accepted_predicates` is READ-ONLY widening: it lets the trace
+ * readers accept another engine's predicate URI (a list of https URIs). It
+ * changes no writer and no gate polarity.
  */
 exports.ORG_PROFILE_ALLOWLIST = Object.freeze([
     'vault.provider',
@@ -73,6 +108,8 @@ exports.ORG_PROFILE_ALLOWLIST = Object.freeze([
     'vault.fallback_ref',
     'vault.fallback_host',
     'platform.host',
+    exports.VAULT_REQUIRED_CONFIG_KEY,
+    exports.VAULT_TRACE_ACCEPTED_PREDICATES_KEY,
 ]);
 /**
  * The single top-level key naming the Phase 34 init-only seed section.
@@ -220,62 +257,108 @@ function describeUnknown(value) {
         return Object.prototype.toString.call(value);
     }
 }
-// ─── resolveGlobalPackageRoot ────────────────────────────────────────────────
+// ─── Global package roots ────────────────────────────────────────────────────
 /**
- * D-03's "global" half of the two-path resolution ladder, as a pure
- * heuristic with NO subprocess spawn (this repo avoids spawning a
- * subprocess for a computation that does not strictly require one):
+ * D-03's "global" half of the two-path resolution ladder, as a pure heuristic
+ * with NO subprocess spawn. Returns an ORDERED list of existing candidate
+ * roots (a single root silently missed Homebrew layouts):
  *
  * 1. `NPM_CONFIG_PREFIX` / `npm_config_prefix`, when set to a non-blank
  *    string: `<prefix>/node_modules` on `win32`, `<prefix>/lib/node_modules`
  *    otherwise.
- * 2. Otherwise, derived from `process.execPath`: with
- *    `execDir = path.dirname(process.execPath)`, `path.join(execDir,
- *    'node_modules')` on `win32`, `path.resolve(execDir, '..', 'lib',
- *    'node_modules')` otherwise.
+ * 2. Every PATH directory containing a `node` entry, mapped through the same
+ *    `<bin>` → `<global tree>` rule — WITHOUT resolving symlinks. This is what
+ *    finds Homebrew: `process.execPath` resolves `/opt/homebrew/bin/node` into
+ *    the Cellar, whose `lib/node_modules` exists but holds only npm, while the
+ *    real global tree lives at `/opt/homebrew/lib/node_modules` beside the
+ *    PATH symlink.
+ * 3. Derived from `process.execPath` — still correct for nvm/Volta layouts.
  *
- * The candidate is returned only when `fs.existsSync(candidate)`;
- * otherwise `null`.
+ * Candidates are deduped and filtered to `fs.existsSync`; resolution tries
+ * each in order (first hit wins), so an existing-but-empty earlier root cannot
+ * mask a later root that holds the package.
  *
- * Accepted residual: an nvm/Volta-style layout that honours neither
- * `NPM_CONFIG_PREFIX` nor places the global tree beside the node binary
- * will simply not resolve a globally-installed profile — this degrades
- * per D-09 (falls through to the no-profile behaviour with a warning)
- * rather than failing.
+ * Detection (the `/pp-init` org-profile hint and its invariant check) passes
+ * `explicitPrefixOnly: true`: with `NPM_CONFIG_PREFIX` set, only the prefix
+ * root is scanned, because a hint must never come from a tree the operator did
+ * not point at. Detection roots are therefore a subset of resolution roots.
  *
- * pp-core's own install directory is deliberately NOT a candidate here:
- * the AI-runtime install is a bare directory copy with no `package.json`
- * and no `node_modules` of its own, so resolving relative to it would
- * never find a sibling package.
+ * pp-core's own install directory is deliberately NOT a candidate: the
+ * runtime install is a bare directory copy with no `node_modules` of its own.
  */
-function resolveGlobalPackageRoot() {
+const GLOBAL_ROOT_PATH_SCAN_CAP = 64;
+/** npm's own `<bin dir>` → `<global node_modules>` mapping. */
+function globalRootFromBinDir(binDir) {
+    return process.platform === 'win32' ? node_path_1.default.join(binDir, 'node_modules') : node_path_1.default.resolve(binDir, '..', 'lib', 'node_modules');
+}
+function resolveGlobalPackageRootCandidates(opts = {}) {
+    const candidates = [];
+    const push = (c) => {
+        if (!candidates.includes(c))
+            candidates.push(c);
+    };
+    const existing = () => candidates.filter((c) => {
+        try {
+            return node_fs_1.default.existsSync(c);
+        }
+        catch {
+            return false;
+        }
+    });
     try {
         const prefixEnv = process.env.NPM_CONFIG_PREFIX ?? process.env.npm_config_prefix;
-        let candidate;
         if (typeof prefixEnv === 'string' && prefixEnv.trim() !== '') {
             const prefix = prefixEnv.trim();
-            candidate =
-                process.platform === 'win32' ? node_path_1.default.join(prefix, 'node_modules') : node_path_1.default.join(prefix, 'lib', 'node_modules');
+            push(process.platform === 'win32' ? node_path_1.default.join(prefix, 'node_modules') : node_path_1.default.join(prefix, 'lib', 'node_modules'));
+            // An explicit prefix is authoritative for detection; one that points
+            // nowhere yields [] — never a fall-through to PATH.
+            if (opts.explicitPrefixOnly === true)
+                return existing();
         }
-        else {
-            const execDir = node_path_1.default.dirname(process.execPath);
-            candidate =
-                process.platform === 'win32'
-                    ? node_path_1.default.join(execDir, 'node_modules')
-                    : node_path_1.default.resolve(execDir, '..', 'lib', 'node_modules');
+        const pathDirs = (process.env.PATH ?? '')
+            .split(node_path_1.default.delimiter)
+            .filter((d) => d.trim() !== '')
+            .slice(0, GLOBAL_ROOT_PATH_SCAN_CAP);
+        const nodeNames = process.platform === 'win32' ? ['node.exe', 'node.cmd', 'node'] : ['node'];
+        for (const dir of pathDirs) {
+            for (const name of nodeNames) {
+                let found = false;
+                try {
+                    found = node_fs_1.default.existsSync(node_path_1.default.join(dir, name));
+                }
+                catch {
+                    // unreadable PATH entry — skip it
+                }
+                if (found) {
+                    push(globalRootFromBinDir(dir));
+                    break;
+                }
+            }
         }
-        return node_fs_1.default.existsSync(candidate) ? candidate : null;
+        push(globalRootFromBinDir(node_path_1.default.dirname(process.execPath)));
     }
     catch {
-        return null;
+        // degrade to whatever was collected before the fault
     }
+    return existing();
+}
+/**
+ * Map the `_globalRoot` test seam (a single root, or `null` for "no global
+ * root found") onto the candidate-list shape; when the seam is absent, run the
+ * production heuristic. The seam wins over `explicitPrefixOnly`.
+ */
+function globalRootCandidatesFor(opts) {
+    if (opts && opts._globalRoot !== undefined) {
+        return opts._globalRoot === null ? [] : [opts._globalRoot];
+    }
+    return resolveGlobalPackageRootCandidates({ explicitPrefixOnly: opts?.explicitPrefixOnly === true });
 }
 // ─── resolveProfilePackage ───────────────────────────────────────────────────
 /**
  * D-03's two-path resolution ladder. Attempt `require.resolve(pkgName +
  * '/package.json', { paths: [cwd] })` first and report `source: 'project'`;
- * on failure attempt the same with `paths: [globalRoot]` when a global root
- * was found and report `source: 'global'`; otherwise `null`. The
+ * on failure attempt the same with `paths: [root]` for each global candidate
+ * root in order and report `source: 'global'`; otherwise `null`. The
  * project-local hit always wins when both would resolve — the global
  * attempt is only ever reached when the project attempt threw.
  *
@@ -283,19 +366,19 @@ function resolveGlobalPackageRoot() {
  * 220-228): the same try/catch-returns-null shape, one level removed
  * (resolving a data file's sibling `package.json`, not a CLI entry point).
  */
-function resolveProfilePackage(pkgName, cwd, globalRoot) {
+function resolveProfilePackage(pkgName, cwd, globalRoots) {
     try {
         return { pkgJsonPath: require.resolve(`${pkgName}/package.json`, { paths: [cwd] }), source: 'project' };
     }
     catch {
-        // fall through to the global attempt below
+        // fall through to the global attempts below
     }
-    if (globalRoot) {
+    for (const globalRoot of globalRoots) {
         try {
             return { pkgJsonPath: require.resolve(`${pkgName}/package.json`, { paths: [globalRoot] }), source: 'global' };
         }
         catch {
-            // fall through to null below
+            // try the next candidate root
         }
     }
     return null;
@@ -388,6 +471,45 @@ function flattenProfileDocument(doc) {
  */
 function profileValueDisposition(key, value) {
     try {
+        // The one boolean-typed member, disposed of before the string-only scalar
+        // guard below would reject its natural JSON form. Carried as the canonical
+        // string "true" / "false".
+        if (key === exports.VAULT_REQUIRED_CONFIG_KEY) {
+            if (value === true || value === false)
+                return { ok: true, value: String(value) };
+            if (typeof value === 'string') {
+                const t = value.trim();
+                if (t === 'true' || t === 'false')
+                    return { ok: true, value: t };
+            }
+            return { ok: false, reason: 'value must be the boolean true or false' };
+        }
+        // The one list-typed member. Carried forward as a canonical JSON array
+        // string, so `contributes` stays a string map.
+        if (key === exports.VAULT_TRACE_ACCEPTED_PREDICATES_KEY) {
+            const list = Array.isArray(value) ? value : null;
+            if (list === null || list.length === 0) {
+                return { ok: false, reason: 'value must be a non-empty list of https URIs' };
+            }
+            if (list.length > exports.TRACE_ACCEPTED_PREDICATES_CAP) {
+                return { ok: false, reason: `value lists more than ${exports.TRACE_ACCEPTED_PREDICATES_CAP} URIs` };
+            }
+            const kept = [];
+            for (const item of list) {
+                if (typeof item !== 'string')
+                    return { ok: false, reason: 'every entry must be a string' };
+                const t = item.trim();
+                if (t.length > exports.TRACE_ACCEPTED_PREDICATE_MAX) {
+                    return { ok: false, reason: `an entry is longer than ${exports.TRACE_ACCEPTED_PREDICATE_MAX} characters` };
+                }
+                if (!/^https:\/\/[^\s\x00-\x1f\x7f"'<>`\\]+$/.test(t)) {
+                    return { ok: false, reason: 'every entry must be an https URI with no whitespace or quotes' };
+                }
+                if (!kept.includes(t))
+                    kept.push(t);
+            }
+            return { ok: true, value: JSON.stringify(kept) };
+        }
         if (typeof value !== 'string') {
             return { ok: false, reason: 'value must be a string' };
         }
@@ -458,7 +580,7 @@ function profileValueDisposition(key, value) {
  * The `_globalRoot` option is the repo's `_`-prefixed test seam convention
  * (as used by `_vault` / `_exec` / `_writeBack` in
  * `src/vault-command-router.cts`); production callers omit it and the
- * module calls `resolveGlobalPackageRoot()`. Passing `_globalRoot`
+ * module walks `resolveGlobalPackageRootCandidates()`. Passing `_globalRoot`
  * explicitly (including `null`, to simulate "no global root found")
  * overrides the production heuristic for that one call.
  *
@@ -498,16 +620,19 @@ function resolveOrgProfileDocument(cwd, opts) {
         if (pkgName === '') {
             return absentDocShape();
         }
-        // Step 2: resolve the package (project, then global).
-        const globalRoot = opts && opts._globalRoot !== undefined ? opts._globalRoot : resolveGlobalPackageRoot();
-        const hit = resolveProfilePackage(pkgName, cwd, globalRoot);
+        // Step 2: resolve the package (project, then every global candidate).
+        const globalRoots = globalRootCandidatesFor(opts);
+        const hit = resolveProfilePackage(pkgName, cwd, globalRoots);
         if (!hit) {
             const echoed = sanitizeForWarning(pkgName);
+            const probed = globalRoots.length > 0
+                ? `the global npm root(s) ${globalRoots.map((r) => sanitizeForWarning(r)).join(', ')}`
+                : 'no locatable global npm root';
             return {
                 ...absentDocShape(),
                 configured: pkgName,
                 warnings: [
-                    bound(`org profile "${echoed}" was not found — resolution was attempted from the project and the global npm root and found nothing. Falling back to built-in defaults.`),
+                    bound(`org profile "${echoed}" was not found — resolution was attempted from the project and ${probed} and found nothing. Falling back to built-in defaults.`),
                 ],
             };
         }
@@ -694,3 +819,52 @@ function readProfileValue(cwd, key, opts) {
         source: resolution.source,
     };
 }
+/**
+ * The ONE ladder for `vault.required`, which `computeVaultVerdict` (the
+ * verdict owner) and `vault org-profile` both read:
+ *
+ * 1. The project's `.planning/config.json`. A present value wins, whatever
+ *    it is: a JSON boolean is used as is; anything else is treated as false
+ *    and reported as invalid (the gate card names it), never passed on to the
+ *    profile — an explicit project value is the project's decision.
+ * 2. The org profile, already narrowed to "true" / "false" by the value guard.
+ * 3. The registered default, false.
+ *
+ * Never throws.
+ */
+function resolveVaultRequired(cwd, opts) {
+    try {
+        const raw = cfgGet(cwd, exports.VAULT_REQUIRED_CONFIG_KEY, undefined);
+        if (raw !== undefined) {
+            return { required: raw === true, source: 'config', valid: typeof raw === 'boolean', raw, warnings: [] };
+        }
+        const profile = readProfileValue(cwd, exports.VAULT_REQUIRED_CONFIG_KEY, opts);
+        if (profile.value === 'true' || profile.value === 'false') {
+            return { required: profile.value === 'true', source: 'profile', valid: true, raw: undefined, warnings: profile.warnings };
+        }
+        return { required: false, source: 'default', valid: true, raw: undefined, warnings: profile.warnings };
+    }
+    catch {
+        return { required: false, source: 'default', valid: true, raw: undefined, warnings: [] };
+    }
+}
+// ─── resolveAcceptedTracePredicates ──────────────────────────────────────────
+/**
+ * The extra practice-trace predicate types the org profile lists under
+ * `vault.trace.accepted_predicates` — `[]` when there is no profile, the key is
+ * absent, or its value was refused by the value guard. Org profile only: a
+ * project config value is not read (the key is not a project setting). Never
+ * throws.
+ */
+function resolveAcceptedTracePredicates(cwd, opts) {
+    try {
+        const profile = readProfileValue(cwd, exports.VAULT_TRACE_ACCEPTED_PREDICATES_KEY, opts);
+        if (typeof profile.value !== 'string')
+            return [];
+        const parsed = JSON.parse(profile.value);
+        return Array.isArray(parsed) ? parsed.filter((v) => typeof v === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}

package/pp-core/bin/lib/phase-command-router.cjs

@@ -6,7 +6,7 @@
  * Unsupported in this router:
  * - scaffold: routed through top-level scaffold command.
  *
- * CJS-only subcommands: mvp-mode, dispatch-plan, install-run, tier, tier-propose (dispatched directly, before hub).
+ * CJS-only subcommands: mvp-mode, dispatch-plan, install-run, tier, tier-propose, manifest (dispatched directly, before hub).
  *
  * #3788: dispatch is mediated by CommandRoutingHub. The public entry point
  * and observable CLI behaviour are unchanged.
@@ -73,6 +73,12 @@ function routePhaseCommand({ phase, args, cwd, raw, error }) {
         phase.cmdPhaseTierPropose(cwd, args.slice(2), raw);
         return;
     }
+    // `manifest start|record` (pack 10): write `.phase-manifest.json`, which
+    // `/pp-undo --phase` reads (src/phase-manifest.cts).
+    if (subcommand === 'manifest') {
+        phase.cmdPhaseManifest(cwd, args.slice(2), raw);
+        return;
+    }
     // ── Build the CJS registry ──────────────────────────────────────────────────
     // Each handler receives a ctx object from the hub and must return a HubResult.
     const cjsRegistry = {