@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/policy/environment.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * Shared environment-resolution helper. Replaces the three near-duplicate
+ * implementations that grew up across `recipe/tasks/shared.ts:resolveTenant`,
+ * `deploy/tasks/shared.ts:getDeployContext`, and the hand-copied
+ * `resolveAuthoringEnvironment` blocks in `deploy/tasks/site.ts` and
+ * `deploy/tasks/site-bind.ts` — all doing the same
+ * readRoot → defaultEnvProfile → environment-or-throw dance with slightly
+ * different error messages and return shapes.
+ *
+ * Domain-specific wrappers (recipe `resolveTenant`, deploy
+ * `getDeployContext`) compose this and add their own decoration
+ * (auth client, deploy token lookup, etc.).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveEnvironment = void 0;
+const root_config_1 = require("../config/root-config");
+const errors_1 = require("../shared/errors");
+const cli_tasks_1 = require("../shared/cli-tasks");
+const enforce_1 = require("./enforce");
+const resolveEnvironment = (options) => {
+    const configPath = options.config ?? process.cwd();
+    const rootFile = (0, root_config_1.readRootConfigurationFile)(configPath);
+    const envName = options.environmentName ?? rootFile.config.defaultEnvProfile;
+    if (!envName) {
+        throw (0, errors_1.createScaiError)("Environment name is required.", "INPUT_INVALID", {
+            hint: "Pass --environment-name or set defaultEnvProfile in the config.",
+        });
+    }
+    const root = (0, root_config_1.readRootConfiguration)(configPath, envName);
+    const environment = root.environments[envName];
+    if (!environment) {
+        throw (0, errors_1.createScaiError)(`Environment '${envName}' is not configured.`, "ENV_NOT_FOUND", {
+            hint: "Run 'scai setup init' to configure the environment.",
+        });
+    }
+    // Deny-by-default environment gate. A no-op in "unmanaged mode" (no
+    // ~/.sitecoreai/policy.json). See docs/policy-and-guardrails.md.
+    if (!options.skipPolicy) {
+        (0, enforce_1.enforceEnvironmentPolicy)({ envName, environment, configRootDir: rootFile.rootDir });
+    }
+    return { envName, environment, root, timeoutMs: (0, cli_tasks_1.resolveApiTimeoutMs)(root) };
+};
+exports.resolveEnvironment = resolveEnvironment;

package/dist/policy/identity.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Environment identity extraction and drift detection — the Phase 1
+ * trust-on-first-use mechanism. The allowlist catches *new* environments;
+ * the identity pin catches an enrolled environment name whose tenant
+ * triple has been *swapped* underneath it.
+ */
+import type { EnvironmentConfiguration } from "../config/types";
+import type { EnvIdentity } from "./types";
+/**
+ * Extract the pinnable identity (tenant triple + host) from an env
+ * profile. Fields the profile doesn't carry are omitted, so the pin only
+ * ever asserts what was actually known at enrollment time.
+ */
+export declare const extractIdentity: (env: EnvironmentConfiguration) => EnvIdentity;
+/**
+ * Compare a current identity against a pinned one. Only fields present in
+ * the PIN are checked — the pin is the contract. A pinned field that is
+ * missing or different in `current` counts as drift. Returns a list of
+ * human-readable drift descriptions; an empty list means the identity
+ * still matches.
+ */
+export declare const describeIdentityDrift: (pinned: EnvIdentity, current: EnvIdentity) => string[];
+/** Whether `current` still matches everything the `pinned` identity asserts. */
+export declare const identityMatchesPin: (pinned: EnvIdentity, current: EnvIdentity) => boolean;

package/dist/policy/identity.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * Environment identity extraction and drift detection — the Phase 1
+ * trust-on-first-use mechanism. The allowlist catches *new* environments;
+ * the identity pin catches an enrolled environment name whose tenant
+ * triple has been *swapped* underneath it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.identityMatchesPin = exports.describeIdentityDrift = exports.extractIdentity = void 0;
+/** The identity-pin fields, in display order. */
+const IDENTITY_FIELDS = [
+    "organizationId",
+    "projectId",
+    "environmentId",
+    "host",
+];
+/**
+ * Extract the pinnable identity (tenant triple + host) from an env
+ * profile. Fields the profile doesn't carry are omitted, so the pin only
+ * ever asserts what was actually known at enrollment time.
+ */
+const extractIdentity = (env) => {
+    const identity = {};
+    if (env.organizationId)
+        identity.organizationId = env.organizationId;
+    if (env.projectId)
+        identity.projectId = env.projectId;
+    if (env.environmentId)
+        identity.environmentId = env.environmentId;
+    if (env.host)
+        identity.host = env.host;
+    return identity;
+};
+exports.extractIdentity = extractIdentity;
+/**
+ * Compare a current identity against a pinned one. Only fields present in
+ * the PIN are checked — the pin is the contract. A pinned field that is
+ * missing or different in `current` counts as drift. Returns a list of
+ * human-readable drift descriptions; an empty list means the identity
+ * still matches.
+ */
+const describeIdentityDrift = (pinned, current) => {
+    const drift = [];
+    for (const field of IDENTITY_FIELDS) {
+        const pin = pinned[field];
+        if (pin === undefined) {
+            continue;
+        }
+        if (current[field] !== pin) {
+            drift.push(`${field}: pinned '${pin}', config now has '${current[field] ?? "(unset)"}'`);
+        }
+    }
+    return drift;
+};
+exports.describeIdentityDrift = describeIdentityDrift;
+/** Whether `current` still matches everything the `pinned` identity asserts. */
+const identityMatchesPin = (pinned, current) => (0, exports.describeIdentityDrift)(pinned, current).length === 0;
+exports.identityMatchesPin = identityMatchesPin;

package/dist/policy/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * scai workspace-policy guardrails — the operator-owned layer that bounds
+ * which Sitecore environments scai may operate against, deny-by-default.
+ *
+ * See docs/policy-and-guardrails.md for the design and threat model.
+ */
+export { enforceEnvironmentPolicy } from "./enforce";
+export type { EnforceEnvironmentPolicyParams } from "./enforce";
+export { authorizeOperation } from "./authorize";
+export type { AuthorizeOperationParams } from "./authorize";
+export { resolveCallerContext } from "./caller";
+export type { CallerContext, CallerKind } from "./caller";
+export { enrollEnvironment, repinEnvironment, setEnvironmentFlags, unenrollEnvironment, } from "./enroll";
+export type { EnrollEnvironmentParams, EnrollResult, EnvironmentFlags } from "./enroll";
+export { resolveEffectivePolicy } from "./resolve";
+export { OPERATION_RISK, riskTierForOperation } from "./operations";
+export type { OperationId } from "./operations";
+export { isManaged, readRepoPolicy, readWorkspacePolicy, writeWorkspacePolicy } from "./store";
+export { describeIdentityDrift, extractIdentity, identityMatchesPin } from "./identity";
+export { resolvePolicyDir, resolveRepoPolicyPath, resolveUserPolicyPath } from "./paths";
+export { RISK_TIERS, minTier, riskRank } from "./types";
+export type { EffectivePolicy, EnrollSource, EnvIdentity, PolicyEnvironment, RepoPolicy, RiskTier, WorkspacePolicy, } from "./types";

package/dist/policy/index.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * scai workspace-policy guardrails — the operator-owned layer that bounds
+ * which Sitecore environments scai may operate against, deny-by-default.
+ *
+ * See docs/policy-and-guardrails.md for the design and threat model.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.riskRank = exports.minTier = exports.RISK_TIERS = exports.resolveUserPolicyPath = exports.resolveRepoPolicyPath = exports.resolvePolicyDir = exports.identityMatchesPin = exports.extractIdentity = exports.describeIdentityDrift = exports.writeWorkspacePolicy = exports.readWorkspacePolicy = exports.readRepoPolicy = exports.isManaged = exports.riskTierForOperation = exports.OPERATION_RISK = exports.resolveEffectivePolicy = exports.unenrollEnvironment = exports.setEnvironmentFlags = exports.repinEnvironment = exports.enrollEnvironment = exports.resolveCallerContext = exports.authorizeOperation = exports.enforceEnvironmentPolicy = void 0;
+var enforce_1 = require("./enforce");
+Object.defineProperty(exports, "enforceEnvironmentPolicy", { enumerable: true, get: function () { return enforce_1.enforceEnvironmentPolicy; } });
+var authorize_1 = require("./authorize");
+Object.defineProperty(exports, "authorizeOperation", { enumerable: true, get: function () { return authorize_1.authorizeOperation; } });
+var caller_1 = require("./caller");
+Object.defineProperty(exports, "resolveCallerContext", { enumerable: true, get: function () { return caller_1.resolveCallerContext; } });
+var enroll_1 = require("./enroll");
+Object.defineProperty(exports, "enrollEnvironment", { enumerable: true, get: function () { return enroll_1.enrollEnvironment; } });
+Object.defineProperty(exports, "repinEnvironment", { enumerable: true, get: function () { return enroll_1.repinEnvironment; } });
+Object.defineProperty(exports, "setEnvironmentFlags", { enumerable: true, get: function () { return enroll_1.setEnvironmentFlags; } });
+Object.defineProperty(exports, "unenrollEnvironment", { enumerable: true, get: function () { return enroll_1.unenrollEnvironment; } });
+var resolve_1 = require("./resolve");
+Object.defineProperty(exports, "resolveEffectivePolicy", { enumerable: true, get: function () { return resolve_1.resolveEffectivePolicy; } });
+var operations_1 = require("./operations");
+Object.defineProperty(exports, "OPERATION_RISK", { enumerable: true, get: function () { return operations_1.OPERATION_RISK; } });
+Object.defineProperty(exports, "riskTierForOperation", { enumerable: true, get: function () { return operations_1.riskTierForOperation; } });
+var store_1 = require("./store");
+Object.defineProperty(exports, "isManaged", { enumerable: true, get: function () { return store_1.isManaged; } });
+Object.defineProperty(exports, "readRepoPolicy", { enumerable: true, get: function () { return store_1.readRepoPolicy; } });
+Object.defineProperty(exports, "readWorkspacePolicy", { enumerable: true, get: function () { return store_1.readWorkspacePolicy; } });
+Object.defineProperty(exports, "writeWorkspacePolicy", { enumerable: true, get: function () { return store_1.writeWorkspacePolicy; } });
+var identity_1 = require("./identity");
+Object.defineProperty(exports, "describeIdentityDrift", { enumerable: true, get: function () { return identity_1.describeIdentityDrift; } });
+Object.defineProperty(exports, "extractIdentity", { enumerable: true, get: function () { return identity_1.extractIdentity; } });
+Object.defineProperty(exports, "identityMatchesPin", { enumerable: true, get: function () { return identity_1.identityMatchesPin; } });
+var paths_1 = require("./paths");
+Object.defineProperty(exports, "resolvePolicyDir", { enumerable: true, get: function () { return paths_1.resolvePolicyDir; } });
+Object.defineProperty(exports, "resolveRepoPolicyPath", { enumerable: true, get: function () { return paths_1.resolveRepoPolicyPath; } });
+Object.defineProperty(exports, "resolveUserPolicyPath", { enumerable: true, get: function () { return paths_1.resolveUserPolicyPath; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "RISK_TIERS", { enumerable: true, get: function () { return types_1.RISK_TIERS; } });
+Object.defineProperty(exports, "minTier", { enumerable: true, get: function () { return types_1.minTier; } });
+Object.defineProperty(exports, "riskRank", { enumerable: true, get: function () { return types_1.riskRank; } });

package/dist/policy/operations.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Operation risk registry — the single, auditable classification of
+ * scai's mutating operations by risk tier (Phase 3).
+ *
+ * Anything not listed here is `write`. Listing an operation as
+ * `destructive` makes `ensureAllowWrite(root, env, override, id)` — and
+ * thus every CLI / SDK / MCP path that runs it — authorize at the
+ * `destructive` tier: refused for `m2m` / `mcp` callers, and for a `ci`
+ * caller without `ciWrites`. See docs/policy-and-guardrails.md.
+ *
+ * A security reviewer reads this one file to see everything scai treats
+ * as irreversible.
+ */
+import type { RiskTier } from "./types";
+/** Stable id of a risk-classified mutating operation. */
+export type OperationId = "cleanup-versions-prune" | "cleanup-archive-purge" | "cleanup-dead-templates" | "cleanup-duplicates" | "cleanup-subtree" | "cleanup-roles" | "cleanup-users" | "cleanup-site-residue" | "recipe-push" | "deploy-environment-delete" | "deploy-project-delete";
+/**
+ * Risk tier of each classified operation. Every entry here is currently
+ * `destructive` (irreversible); the `RiskTier` value type leaves room to
+ * classify an operation at another tier later without a shape change.
+ */
+export declare const OPERATION_RISK: Record<OperationId, RiskTier>;
+/** The risk tier of an operation. */
+export declare const riskTierForOperation: (operation: OperationId) => RiskTier;

package/dist/policy/operations.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * Operation risk registry — the single, auditable classification of
+ * scai's mutating operations by risk tier (Phase 3).
+ *
+ * Anything not listed here is `write`. Listing an operation as
+ * `destructive` makes `ensureAllowWrite(root, env, override, id)` — and
+ * thus every CLI / SDK / MCP path that runs it — authorize at the
+ * `destructive` tier: refused for `m2m` / `mcp` callers, and for a `ci`
+ * caller without `ciWrites`. See docs/policy-and-guardrails.md.
+ *
+ * A security reviewer reads this one file to see everything scai treats
+ * as irreversible.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.riskTierForOperation = exports.OPERATION_RISK = void 0;
+/**
+ * Risk tier of each classified operation. Every entry here is currently
+ * `destructive` (irreversible); the `RiskTier` value type leaves room to
+ * classify an operation at another tier later without a shape change.
+ */
+exports.OPERATION_RISK = {
+    "cleanup-versions-prune": "destructive",
+    "cleanup-archive-purge": "destructive",
+    "cleanup-dead-templates": "destructive",
+    "cleanup-duplicates": "destructive",
+    "cleanup-subtree": "destructive",
+    "cleanup-roles": "destructive",
+    "cleanup-users": "destructive",
+    "cleanup-site-residue": "destructive",
+    "recipe-push": "destructive",
+    "deploy-environment-delete": "destructive",
+    "deploy-project-delete": "destructive",
+};
+/** The risk tier of an operation. */
+const riskTierForOperation = (operation) => exports.OPERATION_RISK[operation];
+exports.riskTierForOperation = riskTierForOperation;

package/dist/policy/organization.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared organization-resolution helper — the org-scoped counterpart to
+ * `resolveEnvironment` in `./environment.ts`.
+ *
+ * `brief`, `campaign`, and `brand` act on a Sitecore **organization**,
+ * not an XM Cloud **environment**: their APIs are org-keyed (one brand
+ * credential per org, one region per org, briefs/campaigns live at org
+ * scope). They must not require `--environment-name` / `defaultEnvProfile`
+ * the way `resolveEnvironment` does — an operator with a single
+ * environment, or none at all, should still be able to run them.
+ *
+ * This consolidates the resolution `brand/credential.ts` already did
+ * inline (`resolveBrandOrgId`) so brief and campaign get the same
+ * behaviour instead of dragging in the env-requiring resolver purely to
+ * read `environment.organizationId`.
+ *
+ * Unlike `resolveEnvironment` this does **not** run `enforceEnvironmentPolicy`:
+ * the workspace policy gate is environment-scoped, and org-scoped
+ * commands do not act on a specific environment's tenant data. `brand`
+ * already skips the gate for the same reason.
+ */
+import type { EnvironmentConfiguration, RootConfiguration } from "../config/types";
+export interface ResolveOrganizationOptions {
+    /** Base directory for resolving `sitecoreai.cli.json`; defaults to cwd. */
+    config?: string;
+    /** Explicit organization id (e.g. from `--org-id`). Highest priority. */
+    orgId?: string;
+    /** Explicit env profile name (e.g. from `-n` / `--environment-name`). */
+    environmentName?: string;
+}
+export interface ResolvedOrganization {
+    /** The resolved Sitecore organization id. */
+    orgId: string;
+    /** The full root configuration. */
+    root: RootConfiguration;
+    /**
+     * An env profile belonging to `orgId`, when one exists — the env that
+     * was explicitly named, else the first profile carrying this org.
+     * `undefined` when the org was resolved purely from `--org-id` (or the
+     * sole `brand` entry) and no env profile references it. Consumers that
+     * need an env-scoped automation client read this; those that only need
+     * the org id ignore it.
+     */
+    environment?: EnvironmentConfiguration;
+    /** Name of `environment`, when one was resolved. */
+    envName?: string;
+}
+/**
+ * Resolve the Sitecore organization an org-scoped command should act on.
+ *
+ * Resolution order:
+ *   1. Explicit `orgId` (`--org-id`).
+ *   2. The explicitly named env profile's `organizationId` (`-n` or a
+ *      configured `defaultEnvProfile`) — a named env is authoritative.
+ *   3. The first env profile that carries an `organizationId` — so a
+ *      single-environment config resolves with no flag and no default.
+ *   4. The sole `brand[orgId]` credential entry, when exactly one exists.
+ *
+ * Throws `INPUT_INVALID` when none yields an org id, and `ENV_NOT_FOUND`
+ * when an explicitly named env profile does not exist.
+ */
+export declare const resolveOrganization: (options: ResolveOrganizationOptions) => ResolvedOrganization;

package/dist/policy/organization.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Shared organization-resolution helper — the org-scoped counterpart to
+ * `resolveEnvironment` in `./environment.ts`.
+ *
+ * `brief`, `campaign`, and `brand` act on a Sitecore **organization**,
+ * not an XM Cloud **environment**: their APIs are org-keyed (one brand
+ * credential per org, one region per org, briefs/campaigns live at org
+ * scope). They must not require `--environment-name` / `defaultEnvProfile`
+ * the way `resolveEnvironment` does — an operator with a single
+ * environment, or none at all, should still be able to run them.
+ *
+ * This consolidates the resolution `brand/credential.ts` already did
+ * inline (`resolveBrandOrgId`) so brief and campaign get the same
+ * behaviour instead of dragging in the env-requiring resolver purely to
+ * read `environment.organizationId`.
+ *
+ * Unlike `resolveEnvironment` this does **not** run `enforceEnvironmentPolicy`:
+ * the workspace policy gate is environment-scoped, and org-scoped
+ * commands do not act on a specific environment's tenant data. `brand`
+ * already skips the gate for the same reason.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveOrganization = void 0;
+const root_config_1 = require("../config/root-config");
+const errors_1 = require("../shared/errors");
+/**
+ * Resolve the Sitecore organization an org-scoped command should act on.
+ *
+ * Resolution order:
+ *   1. Explicit `orgId` (`--org-id`).
+ *   2. The explicitly named env profile's `organizationId` (`-n` or a
+ *      configured `defaultEnvProfile`) — a named env is authoritative.
+ *   3. The first env profile that carries an `organizationId` — so a
+ *      single-environment config resolves with no flag and no default.
+ *   4. The sole `brand[orgId]` credential entry, when exactly one exists.
+ *
+ * Throws `INPUT_INVALID` when none yields an org id, and `ENV_NOT_FOUND`
+ * when an explicitly named env profile does not exist.
+ */
+const resolveOrganization = (options) => {
+    const configPath = options.config ?? process.cwd();
+    const root = (0, root_config_1.readRootConfiguration)(configPath, options.environmentName);
+    const environments = root.environments;
+    // `defaultEnvProfile` is the raw config value (undefined when unset) —
+    // distinct from `defaultEnvironment`, which collapses an unset default
+    // to the literal "default". Only a real flag or configured default
+    // counts as a "named" env.
+    const namedEnvName = options.environmentName ?? root.defaultEnvProfile;
+    /** Pick a representative env profile for an org — named env first. */
+    const envForOrg = (orgId) => {
+        if (namedEnvName && environments[namedEnvName]?.organizationId === orgId) {
+            return { envName: namedEnvName, environment: environments[namedEnvName] };
+        }
+        const match = Object.entries(environments).find(([, env]) => env.organizationId === orgId);
+        return match ? { envName: match[0], environment: match[1] } : {};
+    };
+    // 1. Explicit --org-id.
+    if (options.orgId) {
+        return { orgId: options.orgId, root, ...envForOrg(options.orgId) };
+    }
+    // 2. Named env profile — authoritative. We never fall through to a
+    //    different profile's org behind the operator's back.
+    if (namedEnvName) {
+        const named = environments[namedEnvName];
+        if (!named) {
+            throw (0, errors_1.createScaiError)(`Environment '${namedEnvName}' is not configured.`, "ENV_NOT_FOUND", {
+                hint: "Run 'scai setup init' to configure the environment, or pass --org-id.",
+            });
+        }
+        if (named.organizationId) {
+            return { orgId: named.organizationId, root, envName: namedEnvName, environment: named };
+        }
+        throw (0, errors_1.createScaiError)(`Environment '${namedEnvName}' has no organizationId.`, "INPUT_INVALID", {
+            hint: "Pass --org-id <id>, or set organizationId on the env profile.",
+        });
+    }
+    // 3. First env profile carrying an organizationId.
+    const fromProfile = Object.entries(environments).find(([, env]) => Boolean(env.organizationId));
+    if (fromProfile && fromProfile[1].organizationId) {
+        return {
+            orgId: fromProfile[1].organizationId,
+            root,
+            envName: fromProfile[0],
+            environment: fromProfile[1],
+        };
+    }
+    // 4. The sole brand credential entry.
+    const brandOrgIds = Object.keys(root.brand ?? {});
+    if (brandOrgIds.length === 1) {
+        return { orgId: brandOrgIds[0], root, ...envForOrg(brandOrgIds[0]) };
+    }
+    throw (0, errors_1.createScaiError)("Cannot resolve an organization for this command.", "INPUT_INVALID", {
+        hint: "Pass --org-id <id>, or set organizationId on an env profile in sitecoreai.cli.json.",
+    });
+};
+exports.resolveOrganization = resolveOrganization;

package/dist/policy/paths.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Filesystem locations for the policy artifacts.
+ *
+ * The user-global policy joins the established `~/.sitecoreai/` directory
+ * (alongside `audit.log`, `rollback/`). The repo policy sits next to the
+ * `sitecoreai.cli.json` it narrows.
+ */
+/**
+ * The directory holding the user-global workspace policy.
+ *
+ * Honors `SITECOREAI_POLICY_HOME` so tests run against a temp directory.
+ * Under Vitest with no override it returns `null` — the real
+ * `~/.sitecoreai/policy.json` can never leak into a test run, and a
+ * `null` directory means "unmanaged mode" everywhere downstream, so the
+ * existing test suite (which has no policy file) is unaffected.
+ */
+export declare const resolvePolicyDir: () => string | null;
+/** Absolute path to the user-global workspace policy, or `null` (see above). */
+export declare const resolveUserPolicyPath: () => string | null;
+/** Path to the optional repo policy, next to the resolved config file. */
+export declare const resolveRepoPolicyPath: (configRootDir: string) => string;

package/dist/policy/paths.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Filesystem locations for the policy artifacts.
+ *
+ * The user-global policy joins the established `~/.sitecoreai/` directory
+ * (alongside `audit.log`, `rollback/`). The repo policy sits next to the
+ * `sitecoreai.cli.json` it narrows.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRepoPolicyPath = exports.resolveUserPolicyPath = exports.resolvePolicyDir = void 0;
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const POLICY_FILE = "policy.json";
+const REPO_POLICY_FILE = "scai.policy.json";
+/**
+ * The directory holding the user-global workspace policy.
+ *
+ * Honors `SITECOREAI_POLICY_HOME` so tests run against a temp directory.
+ * Under Vitest with no override it returns `null` — the real
+ * `~/.sitecoreai/policy.json` can never leak into a test run, and a
+ * `null` directory means "unmanaged mode" everywhere downstream, so the
+ * existing test suite (which has no policy file) is unaffected.
+ */
+const resolvePolicyDir = () => {
+    const override = process.env.SITECOREAI_POLICY_HOME?.trim();
+    if (override) {
+        return node_path_1.default.resolve(override);
+    }
+    if (process.env.VITEST) {
+        return null;
+    }
+    return node_path_1.default.join(node_os_1.default.homedir(), ".sitecoreai");
+};
+exports.resolvePolicyDir = resolvePolicyDir;
+/** Absolute path to the user-global workspace policy, or `null` (see above). */
+const resolveUserPolicyPath = () => {
+    const dir = (0, exports.resolvePolicyDir)();
+    return dir ? node_path_1.default.join(dir, POLICY_FILE) : null;
+};
+exports.resolveUserPolicyPath = resolveUserPolicyPath;
+/** Path to the optional repo policy, next to the resolved config file. */
+const resolveRepoPolicyPath = (configRootDir) => node_path_1.default.join(configRootDir, REPO_POLICY_FILE);
+exports.resolveRepoPolicyPath = resolveRepoPolicyPath;

package/dist/policy/resolve.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Layered policy resolution. Each layer may only NARROW the one above it,
+ * so the effective verdict is the intersection of the user-global policy
+ * and the optional repo policy — never the union.
+ */
+import { type EffectivePolicy } from "./types";
+/**
+ * Compute the effective policy for one environment.
+ *
+ * `configRootDir` is the directory holding `sitecoreai.cli.json`; the
+ * repo policy (`scai.policy.json`), if any, sits beside it. It is
+ * optional — when omitted, the repo-policy narrowing layer is skipped
+ * and only the user-global policy applies.
+ */
+export declare const resolveEffectivePolicy: (envName: string, configRootDir?: string) => EffectivePolicy;

package/dist/policy/resolve.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * Layered policy resolution. Each layer may only NARROW the one above it,
+ * so the effective verdict is the intersection of the user-global policy
+ * and the optional repo policy — never the union.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveEffectivePolicy = void 0;
+const store_1 = require("./store");
+const types_1 = require("./types");
+/**
+ * Compute the effective policy for one environment.
+ *
+ * `configRootDir` is the directory holding `sitecoreai.cli.json`; the
+ * repo policy (`scai.policy.json`), if any, sits beside it. It is
+ * optional — when omitted, the repo-policy narrowing layer is skipped
+ * and only the user-global policy applies.
+ */
+const resolveEffectivePolicy = (envName, configRootDir) => {
+    const workspace = (0, store_1.readWorkspacePolicy)();
+    if (!workspace) {
+        // Unmanaged mode — no user-global policy file exists.
+        return {
+            managed: false,
+            enrolled: false,
+            ceiling: "read",
+            identity: null,
+            mintCredentials: false,
+            ciWrites: false,
+            stepUpMinutes: undefined,
+        };
+    }
+    const wsEnv = workspace.environments[envName];
+    if (!wsEnv) {
+        return {
+            managed: true,
+            enrolled: false,
+            ceiling: "read",
+            identity: null,
+            mintCredentials: false,
+            ciWrites: false,
+            stepUpMinutes: undefined,
+        };
+    }
+    // The repo policy can only narrow: drop the environment from the
+    // allowlist, lower its ceiling, or flip a flag false.
+    const repo = configRootDir ? (0, store_1.readRepoPolicy)(configRootDir) : null;
+    const allowedByRepo = !repo?.allowEnvironments || repo.allowEnvironments.includes(envName);
+    const repoEnv = repo?.environments?.[envName];
+    let ceiling = wsEnv.ceiling;
+    if (repoEnv?.ceiling) {
+        ceiling = (0, types_1.minTier)(ceiling, repoEnv.ceiling);
+    }
+    // Step-up window — a repo policy may only shorten it, never lengthen.
+    const stepUpCandidates = [wsEnv.stepUpMinutes, repoEnv?.stepUpMinutes].filter((value) => typeof value === "number");
+    const stepUpMinutes = stepUpCandidates.length > 0 ? Math.min(...stepUpCandidates) : undefined;
+    return {
+        managed: true,
+        enrolled: allowedByRepo,
+        ceiling,
+        identity: wsEnv.identity,
+        mintCredentials: wsEnv.mintCredentials === true && repoEnv?.mintCredentials !== false,
+        ciWrites: wsEnv.ciWrites === true && repoEnv?.ciWrites !== false,
+        stepUpMinutes,
+    };
+};
+exports.resolveEffectivePolicy = resolveEffectivePolicy;