@quonfig/cli 0.0.71 → 0.0.73

package/dist/commands/workspace.js

@@ -21,7 +21,31 @@ export default class Workspace extends BaseCommand {
         // /userWorkspaces/list is per-token-org-scoped — a single org's JWT
         // only sees that org's workspaces. Iterate every cached org so the
         // listing is comprehensive in multi-org accounts.
-        const allWorkspaces = await this.fetchAllOrgsWorkspaces(orgEntries);
+        const { failures, workspaces: allWorkspaces } = await this.fetchAllOrgsWorkspaces(orgEntries);
+        // qfg-t15h: an empty listing used to be indistinguishable from "your
+        // session is dead", so an expired login rendered as "(no workspaces
+        // yet)" and nudged the user toward creating a duplicate workspace.
+        // When NOTHING could be listed and the cause is auth, fail the way
+        // `qfg pull`/`qfg get` do (get-client.ts:141) instead of printing a
+        // listing we know is a lie.
+        const authFailures = failures.filter((f) => f.auth);
+        if (failures.length === orgEntries.length && authFailures.length > 0) {
+            const label = authFailures.length === 1
+                ? `org ${authFailures[0].orgSlug}`
+                : `orgs ${authFailures.map((f) => f.orgSlug).join(', ')}`;
+            const detail = authFailures.length === 1
+                ? authFailures[0].detail
+                : authFailures.map((f) => `${f.orgSlug}: ${f.detail}`).join('; ');
+            this.error(`Session expired for ${label}: ${detail}. Run \`qfg login\` to re-authenticate.`, { exit: 401 });
+        }
+        // Partial failure keeps the deliberate multi-org isolation above: the
+        // healthy orgs still list, the dead ones say so instead of looking empty.
+        for (const f of failures) {
+            this.logToStderr(f.auth
+                ? `Warning: could not list workspaces for org ${f.orgSlug} — ${f.detail}. Run \`qfg login\` to re-authenticate.`
+                : `Warning: could not list workspaces for org ${f.orgSlug} — ${f.detail}.`);
+        }
+        const failedOrgIds = new Set(failures.map((f) => f.orgId));
         const defaultProfilePin = this.profilePin(authConfig, allWorkspaces);
         const activePin = this.activePin(store, authConfig, allWorkspaces, defaultProfilePin);
         this.log(`Active workspace: ${activePin ?? '(none)'}`);
@@ -37,7 +61,10 @@ export default class Workspace extends BaseCommand {
             for (const group of grouped) {
                 this.log(`  ${group.orgSlug}:`);
                 if (group.workspaces.length === 0) {
-                    this.log('    (no workspaces yet — `qfg workspace create` to add one)');
+                    // qfg-t15h: "yet" is only true if we actually got an answer.
+                    this.log(failedOrgIds.has(group.workosOrgId)
+                        ? '    (could not list workspaces — see warning above)'
+                        : '    (no workspaces yet — `qfg workspace create` to add one)');
                     continue;
                 }
                 for (const w of group.workspaces) {
@@ -56,6 +83,10 @@ export default class Workspace extends BaseCommand {
             activeWorkspace: activePin,
             defaultProfile: defaultProfilePin,
             orgsWithTokens: orgSlugsWithTokens,
+            // qfg-t15h: --json suppresses the stderr warnings, so the failures
+            // have to be in the payload or a script cannot tell an org that
+            // returned nothing from one that could not be asked.
+            failedOrgs: failures.map((f) => ({ orgSlug: f.orgSlug, authFailure: f.auth, reason: f.detail })),
             orgs: grouped.map((g) => ({
                 orgSlug: g.orgSlug,
                 workosOrgId: g.workosOrgId,
@@ -90,28 +121,47 @@ export default class Workspace extends BaseCommand {
     }
     /**
      * Fan out across every cached org's token and merge the results. One org's
-     * stale token doesn't block the others — we verbose-log and continue.
+     * stale token doesn't block the others — that isolation is deliberate for
+     * multi-org accounts. What is NOT ok (qfg-t15h) is losing the fact that an
+     * org failed: each failure is returned so the caller can decide between a
+     * hard session-expired error (nothing listed) and a per-org warning
+     * alongside the orgs that did answer.
      */
     async fetchAllOrgsWorkspaces(orgEntries) {
         const merged = new Map();
-        for (const [orgId] of orgEntries) {
+        const failures = [];
+        for (const [orgId, tokens] of orgEntries) {
+            const orgSlug = tokens.org_slug ?? orgId;
             let jwt;
             try {
                 // eslint-disable-next-line no-await-in-loop
                 jwt = await getValidAccessToken(orgId, this.verboseLog);
             }
             catch (error) {
-                this.verboseLog('workspace: token refresh failed for org', { orgId, error: String(error) });
+                const detail = error instanceof Error ? error.message : String(error);
+                this.verboseLog('workspace: token refresh failed for org', { orgId, error: detail });
+                // A refresh that fails is always an auth failure — the stored
+                // grant is dead (invalid_grant) or there is no refresh token.
+                failures.push({ auth: true, detail, orgId, orgSlug });
                 continue;
             }
             // eslint-disable-next-line no-await-in-loop
-            const list = await this.fetchWorkspaces(jwt);
-            for (const w of list) {
+            const listed = await this.fetchWorkspaces(jwt);
+            if (listed.kind === 'failed') {
+                failures.push({ auth: listed.auth, detail: listed.detail, orgId, orgSlug });
+                continue;
+            }
+            for (const w of listed.entries) {
                 merged.set(w.workspaceId, w);
             }
         }
-        return [...merged.values()];
+        return { failures, workspaces: [...merged.values()] };
     }
+    /**
+     * qfg-t15h: returns a tagged result rather than a bare array, so a 401 or a
+     * dead connection is distinguishable from an org that genuinely has no
+     * workspaces yet.
+     */
     async fetchWorkspaces(jwt) {
         try {
             const res = await fetch(`${getApiUrl()}/api/v1/userWorkspaces/list`, {
@@ -121,15 +171,20 @@ export default class Workspace extends BaseCommand {
             });
             if (!res.ok) {
                 this.verboseLog('workspace: userWorkspaces/list non-OK', { status: res.status });
-                return [];
+                return {
+                    auth: res.status === 401 || res.status === 403,
+                    detail: `workspace listing failed (HTTP ${res.status})`,
+                    kind: 'failed',
+                };
             }
             const body = (await res.json());
             const list = (body.json ?? body);
-            return Array.isArray(list) ? list : [];
+            return { entries: Array.isArray(list) ? list : [], kind: 'ok' };
         }
         catch (error) {
-            this.verboseLog('workspace: userWorkspaces/list failed', { error: String(error) });
-            return [];
+            const detail = error instanceof Error ? error.message : String(error);
+            this.verboseLog('workspace: userWorkspaces/list failed', { error: detail });
+            return { auth: false, detail, kind: 'failed' };
         }
     }
     /**
@@ -164,7 +219,11 @@ export default class Workspace extends BaseCommand {
         catch (error) {
             return this.err(error instanceof Error ? error.message : String(error));
         }
-        const entries = await this.fetchWorkspaces(jwt);
+        const listed = await this.fetchWorkspaces(jwt);
+        if (listed.kind === 'failed') {
+            return this.err(`Failed to resolve workspace "${override}" — ${listed.detail}.`);
+        }
+        const { entries } = listed;
         if (entries.length === 0) {
             return this.err(`Failed to resolve workspace "${override}" — no entries returned.`);
         }

package/dist/index.d.ts

@@ -3,6 +3,27 @@ import { Command } from '@oclif/core';
 import { Client } from '@quonfig/node';
 import type { ProjectEnvId } from '@quonfig/node';
 import { JsonObj, Result } from './result.js';
+/**
+ * The exit code oclif actually recorded on a thrown error.
+ *
+ * `Errors.CLIError` — what `this.error(msg, {exit: N})` throws — stores N on
+ * `oclif.exit` and has NO `exitCode` property at all. Reading `err.exitCode`
+ * therefore collapsed every non-default code (401 on the auth failures in
+ * `resolve-workspace.ts` / `get-client.ts`, for one) down to 1. Exported so the
+ * behaviour is unit-testable. See qfg-hzmb.
+ */
+export declare function errorExitCode(err: unknown): number;
+/**
+ * The code to actually terminate the process with.
+ *
+ * A POSIX exit status is one byte. Several call sites pass an HTTP-flavoured
+ * code — `{exit: 401}` for the auth failures in `get-client.ts` and
+ * `resolve-workspace.ts` — and `process.exit(401)` truncates to 145, which a
+ * shell reads as "killed by signal 17". Anything outside 1-255 therefore
+ * terminates with the plain failure code; the caller's real intent is still
+ * reported verbatim as `error.exitCode` in the `--json` envelope.
+ */
+export declare function processExitCode(err: unknown): number;
 export declare abstract class BaseCommand extends Command {
     static baseFlags: {
         interactive: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
@@ -20,6 +41,15 @@ export declare abstract class BaseCommand extends Command {
         code?: string;
     } & Error): Promise<void>;
     init(): Promise<void>;
+    /**
+     * oclif's default is `{error: err}`, but `message`, `code` and `stack` are
+     * non-enumerable on an Error, so `JSON.stringify` flattens a thrown Error all
+     * the way down to `{}`. Re-attach the useful fields explicitly and keep the
+     * caller's payload alongside them. See qfg-hzmb.
+     */
+    protected toErrorJson(err: unknown): {
+        error: JsonObj;
+    };
 }
 export declare abstract class APICommand extends BaseCommand {
     static baseFlags: {

package/dist/index.js

@@ -1,5 +1,5 @@
 export { run } from '@oclif/core';
-import { Command, Flags } from '@oclif/core';
+import { Command, Errors, Flags } from '@oclif/core';
 import rawGetClient, { unwrapRequest } from './util/get-client.js';
 const globalFlags = {
     interactive: Flags.boolean({
@@ -20,19 +20,71 @@ const globalFlags = {
         helpGroup: 'GLOBAL',
     }),
 };
+const DEFAULT_EXIT_CODE = 1;
+/**
+ * The exit code oclif actually recorded on a thrown error.
+ *
+ * `Errors.CLIError` — what `this.error(msg, {exit: N})` throws — stores N on
+ * `oclif.exit` and has NO `exitCode` property at all. Reading `err.exitCode`
+ * therefore collapsed every non-default code (401 on the auth failures in
+ * `resolve-workspace.ts` / `get-client.ts`, for one) down to 1. Exported so the
+ * behaviour is unit-testable. See qfg-hzmb.
+ */
+export function errorExitCode(err) {
+    const candidate = err;
+    if (typeof candidate?.oclif?.exit === 'number')
+        return candidate.oclif.exit;
+    if (typeof candidate?.exitCode === 'number')
+        return candidate.exitCode;
+    return DEFAULT_EXIT_CODE;
+}
+/**
+ * The code to actually terminate the process with.
+ *
+ * A POSIX exit status is one byte. Several call sites pass an HTTP-flavoured
+ * code — `{exit: 401}` for the auth failures in `get-client.ts` and
+ * `resolve-workspace.ts` — and `process.exit(401)` truncates to 145, which a
+ * shell reads as "killed by signal 17". Anything outside 1-255 therefore
+ * terminates with the plain failure code; the caller's real intent is still
+ * reported verbatim as `error.exitCode` in the `--json` envelope.
+ */
+export function processExitCode(err) {
+    const intended = errorExitCode(err);
+    return Number.isInteger(intended) && intended >= 1 && intended <= 255 ? intended : DEFAULT_EXIT_CODE;
+}
+/** Best available human-readable message for anything that can be thrown or passed to `err()`. */
+function errorMessage(error) {
+    if (typeof error === 'string')
+        return error;
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error !== 'object' || error === null)
+        return String(error);
+    const record = error;
+    if (typeof record.message === 'string')
+        return record.message;
+    if (typeof record.error === 'string')
+        return record.error;
+    return JSON.stringify(error);
+}
 export class BaseCommand extends Command {
     static baseFlags = {
         ...globalFlags,
     };
     static enableJsonFlag = true;
     err = (error, json) => {
+        const message = errorMessage(error);
         if (this.jsonEnabled()) {
-            throw json ?? error;
-        }
-        if (typeof error === 'string') {
-            return this.error(error, { code: 'ERR', exit: 1 });
+            // qfg-hzmb: throw a real CLIError instead of a bare object, so the message
+            // and the exit code survive to catch() and reach stdout. The caller's
+            // structured payload is copied onto it, keeping the older contract that
+            // callers (and tests) read fields such as `missingEnvVar` straight off the
+            // thrown value.
+            const cliError = new Errors.CLIError(message, { code: 'ERR', exit: DEFAULT_EXIT_CODE });
+            Object.assign(cliError, json ?? (typeof error === 'object' && error !== null ? error : {}));
+            throw cliError;
         }
-        this.error(this.toErrorJson(error), { code: 'ERR', exit: 1 });
+        return this.error(message, { code: 'ERR', exit: DEFAULT_EXIT_CODE });
     };
     isVerbose;
     ok = (message, json) => {
@@ -67,19 +119,64 @@ export class BaseCommand extends Command {
     async catch(err) {
         // Override oclif's default error handling to suppress stack traces in production
         // but preserve error messages for tests
+        // `this.exit(n)` throws an ExitError: a control-flow signal, not a failure to
+        // report. `qfg verify --json` and `qfg migrate doctor --json` deliberately
+        // print their payload and *then* exit non-zero (qfg-ez47), so reporting the
+        // ExitError here would append a second JSON document to stdout. Hand it
+        // straight to oclif, which prints nothing and honours `oclif.exit`.
+        if (err instanceof Errors.ExitError || err.code === 'EEXIT') {
+            throw err;
+        }
+        // qfg-hzmb: `this.log()` is a documented no-op whenever jsonEnabled(), so
+        // this override used to print NOTHING for a failing `--json` run — empty
+        // stdout was indistinguishable from an empty success. Emit the structured
+        // envelope on stdout, exactly as oclif's own catch() does.
+        if (this.jsonEnabled()) {
+            this.logJson(this.toErrorJson(err));
+        }
         // In test environment, just re-throw the error
         if (process.env.NODE_ENV === 'test') {
             throw err;
         }
         // In production, log the error message without stack trace
-        this.log(err.message);
-        this.exit(err.exitCode || 1);
+        if (!this.jsonEnabled()) {
+            this.log(err.message);
+        }
+        this.exit(processExitCode(err));
     }
     async init() {
         await super.init();
         const { flags } = await this.parse();
         this.isVerbose = flags.verbose;
     }
+    /**
+     * oclif's default is `{error: err}`, but `message`, `code` and `stack` are
+     * non-enumerable on an Error, so `JSON.stringify` flattens a thrown Error all
+     * the way down to `{}`. Re-attach the useful fields explicitly and keep the
+     * caller's payload alongside them. See qfg-hzmb.
+     */
+    toErrorJson(err) {
+        if (typeof err !== 'object' || err === null) {
+            return { error: { code: 'ERR', exitCode: errorExitCode(err), message: errorMessage(err) } };
+        }
+        // An Error's own *enumerable* properties are the structured payload handed
+        // to `err()` — keep those. `oclif` is internal bookkeeping (surfaced as
+        // `exitCode`), and `stack` is dropped on purpose (oclif.stacktrace=false).
+        const payload = {};
+        for (const [key, value] of Object.entries(err)) {
+            if (key !== 'oclif' && key !== 'stack')
+                payload[key] = value;
+        }
+        const { code } = err;
+        return {
+            error: {
+                ...payload,
+                code: typeof code === 'string' ? code : 'ERR',
+                exitCode: errorExitCode(err),
+                message: errorMessage(err),
+            },
+        };
+    }
 }
 export class APICommand extends BaseCommand {
     static baseFlags = {

package/dist/init/templates.js

@@ -195,6 +195,49 @@ This is a Quonfig workspace repository. See \`CLAUDE.md\` for the complete schem
 4. Filename must match the \`key\` field (e.g. \`my.flag.json\` has \`"key": "my.flag"\`).
 5. Files must be in the correct directory for their \`type\`.
 6. See \`CLAUDE.md\` for the full list of value types, operators, and constraints.
+
+## \`qfg\` or the Quonfig MCP?
+
+Only relevant if this workspace is *also* hosted on a Quonfig account. On the
+fully-local path, editing the JSON in this repo is the whole story.
+
+- **This repo is checked out and you have a shell** -> use \`qfg\`. The files are
+  already on disk, so reading them costs nothing.
+- **Slack, claude.ai, or anywhere without a checkout** -> use the Quonfig MCP
+  server. It reads and writes the hosted workspace directly. Do not try to shell
+  out to \`qfg\` from a surface that has no repo.
+
+Both surfaces cover the same everyday loop — create a flag or config, change what
+an environment serves, set a log level. (\`qfg\` has all of it today; the MCP's
+create/config/log-level verbs land with its v2 write surface.)
+
+## Setting a value KEEPS that environment's targeting rules
+
+Both surfaces write the same way, so learn it once:
+
+\`qfg set-default\` (alias \`toggle\`), \`qfg set-rollout\`, and the MCP
+\`set_flag\`/\`set_config\` verbs replace exactly ONE rule — the environment's
+**fallback**, the unconditional rule at the end of its rule list that decides
+what users receive when no targeting rule matches. Every targeting rule above
+it is kept, and both surfaces report how many. An environment with no rules of
+its own has them copied from default first, so inherited targeting is kept too.
+
+| Surface | By default | To set the value for EVERYONE |
+|---------|------------|-------------------------------|
+| \`qfg set-default\` / \`qfg set-rollout\` | Keeps targeting; reports "Kept N targeting rule(s)" | add \`--replace-targeting\` |
+| MCP \`set_flag\` / \`set_config\` | Keeps targeting; reports the kept count in its result | send \`replaceTargeting: true\` |
+
+Setting the value for everyone DELETES that environment's targeting rules. They
+stay in git history, and the write returns a \`previousCommitSha\` to restore from.
+
+**Still read before you write.** \`qfg info <key>\` (or MCP \`get_flag\`) shows the
+rules your value is about to sit next to. For anything a fallback cannot express —
+multi-rule targeting, reordering, editing one targeting rule — edit the JSON
+directly or use MCP \`set_document\`.
+
+\`qfg log-level --target ...\` and MCP \`set_log_level\` are **surgical** in the same
+way: they upsert the level for the loggers you name and leave every other rule in
+place.
 `;
 }
 // ── Pre-commit hook ────────────────────────────────────────────────────

package/dist/push/run-push.d.ts

@@ -319,4 +319,25 @@ export declare class PushFatalError extends Error {
  * caller has been updated to drop the call entirely.
  */
 export declare const withPushedViaTrailer: (message: string) => string;
+/**
+ * Render the detail half of one push-denial line (qfg-szte).
+ *
+ * The server's `reason` is already a complete sentence: every family in
+ * app-quonfig `authorize-push-files.ts` renders
+ * `Missing required permission to edit <path>: …<requiredPermission>`, so it
+ * names both the path and the slug. The clone path used to append
+ * `, requires <requiredPermission>` on top of that (slug and path twice), and
+ * the bare path used to print the slug alone and throw the reason away — so
+ * the "why" (which environment is protected, which rule reaches the default)
+ * never reached the user.
+ *
+ * Both now render the reason, and add back only the field it does not
+ * already carry. That keeps the line honest against a server that sends a
+ * terser reason than today's without ever duplicating anything.
+ */
+export declare function formatDenialDetail(d: {
+    path: string;
+    reason: string;
+    requiredPermission: string;
+}): string;
 export declare function runPush(input: RunPushInput, deps: RunPushDeps): Promise<RunPushResult>;

package/dist/push/run-push.js

@@ -64,6 +64,27 @@ const sameRepo = (a, b) => normalizeForCompare(a) === normalizeForCompare(b);
  * caller has been updated to drop the call entirely.
  */
 export const withPushedViaTrailer = (message) => message;
+/**
+ * Render the detail half of one push-denial line (qfg-szte).
+ *
+ * The server's `reason` is already a complete sentence: every family in
+ * app-quonfig `authorize-push-files.ts` renders
+ * `Missing required permission to edit <path>: …<requiredPermission>`, so it
+ * names both the path and the slug. The clone path used to append
+ * `, requires <requiredPermission>` on top of that (slug and path twice), and
+ * the bare path used to print the slug alone and throw the reason away — so
+ * the "why" (which environment is protected, which rule reaches the default)
+ * never reached the user.
+ *
+ * Both now render the reason, and add back only the field it does not
+ * already carry. That keeps the line honest against a server that sends a
+ * terser reason than today's without ever duplicating anything.
+ */
+export function formatDenialDetail(d) {
+    const reason = d.reason.trim() || `missing permission ${d.requiredPermission}`;
+    const withPath = reason.includes(d.path) ? reason : `${d.path}: ${reason}`;
+    return withPath.includes(d.requiredPermission) ? withPath : `${withPath} (requires ${d.requiredPermission})`;
+}
 export async function runPush(input, deps) {
     const log = deps.log ?? ((s) => console.log(s));
     const errLog = deps.errLog ?? ((s) => console.error(s));
@@ -272,8 +293,8 @@ export async function runPush(input, deps) {
         if (packResult.kind === 'denied') {
             errLog(`Push denied for ${packResult.denials.length} commit(s):`);
             for (const d of packResult.denials) {
-                // qfg-7429.5 denial line: `<short-sha>  <path>  -- <reason>, requires <requiredPermission>`
-                errLog(`  ${d.commitSha.slice(0, 8)}  ${d.path}  -- ${d.reason}, requires ${d.requiredPermission}`);
+                // qfg-7429.5 denial line, qfg-szte detail: `<short-sha>  <reason>`
+                errLog(`  ${d.commitSha.slice(0, 8)}  ${formatDenialDetail(d)}`);
             }
             if (packResult.suggestedRecovery) {
                 errLog('');
@@ -369,7 +390,9 @@ export async function runPush(input, deps) {
         if (result.kind === 'denied') {
             errLog(`Push denied for ${result.denials.length} file(s):`);
             for (const d of result.denials) {
-                errLog(`  ${d.path}: missing permission ${d.requiredPermission}`);
+                // qfg-szte: was `<path>: missing permission <perm>`, which dropped the
+                // server's reason (the "why") entirely.
+                errLog(`  ${formatDenialDetail(d)}`);
             }
             throw new PushFatalError(`Push denied for ${result.denials.length} file(s). See errors above.`, 'PUSH_DENIED');
         }

package/dist/util/rules.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Rule helpers shared by the CLI's writers (`set-default`, `set-rollout`,
+ * `log-level`) and readers (`info`, `cleanup status`) — beads qfg-qjdm and
+ * qfg-9kr8.
+ *
+ * The CLI cannot import app-quonfig code, so this file is a deliberate,
+ * small mirror of the server's rulebook. Keep the semantics byte-identical
+ * with:
+ *   - app-quonfig src/lib/domain/rule-display.ts  → isCatchAllRule
+ *   - app-quonfig src/lib/public-api/write-scope.ts → countTargetingRules
+ *   - app-quonfig src/lib/public-api/log-level-write.ts → upsertFallbackRule
+ * Both surfaces write the same documents; a second, subtly different
+ * rulebook is a correctness hazard, not a style problem.
+ */
+export type Criterion = {
+    operator?: unknown;
+    [key: string]: unknown;
+};
+export type Rule = {
+    criteria?: Criterion[];
+    value?: unknown;
+    [key: string]: unknown;
+};
+export type EnvRules = {
+    id: string;
+    rules?: Rule[];
+};
+export type ScopedDocument = {
+    default?: {
+        rules?: Rule[];
+    };
+    environments?: EnvRules[];
+};
+/** A fresh unconditional rule carrying `value`. */
+export declare function catchAllRule(value: unknown): Rule;
+/**
+ * THE ONE DEFINITION of "is this rule unconditional" (qfg-gv54).
+ *
+ * A catch-all — the base-case rule that serves everyone in its scope — has
+ * two live JSON spellings, and every SDK evaluator treats them identically:
+ *
+ *   {criteria: [{operator: 'ALWAYS_TRUE'}]}  ← UI, API, MCP, `qfg create`
+ *   {criteria: []}                           ← older `qfg set-default` writes
+ *
+ * Both are in production data and neither is being backfilled (Jeff,
+ * 2026-09-02), so every READER accepts both. Criteria are ANDed, so one
+ * conditional criterion makes the whole rule conditional.
+ *
+ * Fails CLOSED: anything unreadable as a rule (no `criteria` key, not an
+ * object) is NOT a catch-all — the same choice app-quonfig's
+ * `isCatchAllRuleUnknown` makes for raw parsed JSON. On the write path that
+ * means a malformed rule is left alone and a fresh fallback is appended,
+ * rather than a malformed rule being silently overwritten.
+ */
+export declare function isCatchAllRule(rule: unknown): boolean;
+/**
+ * How many real TARGETING rules a scope holds.
+ *
+ * A targeted scope is conventionally `[…targeting rules, catch-all]`: the
+ * trailing unconditional rule is the scope's fallback, not a rule that
+ * targets anyone, so it is discounted. ONLY a trailing catch-all is — an
+ * unconditional rule anywhere earlier shadows every rule after it, which is
+ * a targeting decision in its own right and stays counted.
+ */
+export declare function countTargetingRules(rules: Rule[]): number;
+/**
+ * Set the scope's fallback value WITHOUT disturbing its targeting rules:
+ * the first catch-all's value is replaced in place (criteria untouched — an
+ * existing bare `criteria: []` fallback keeps its spelling, exactly as the
+ * server does), and if the scope has no catch-all at all a fresh
+ * ALWAYS_TRUE rule is appended at the end. Never mutates `rules`.
+ */
+export declare function upsertFallbackRule(rules: Rule[], value: unknown): Rule[];
+/**
+ * The rules a write should start from for one scope.
+ *
+ * `envName` undefined (or empty) means the document's `default` block, which
+ * always exists and is never seeded. A named environment with no block of
+ * its own inherits `default.rules` at evaluation time, so writing it starts
+ * from a DEEP CLONE of those rules — the same shape the UI produces when an
+ * environment stops inheriting. Starting from `[]` instead would silently
+ * drop the inherited targeting for that environment.
+ *
+ * `seeded` is true only when rules were actually copied, so callers do not
+ * report a copy that moved nothing.
+ */
+export declare function seedScopeRules(config: ScopedDocument, envName?: string): {
+    rules: Rule[];
+    seeded: boolean;
+};
+/** The environments array with `envName`'s rules replaced, appending the entry when it has none. */
+export declare function upsertEnvRules(envs: EnvRules[], envName: string, rules: Rule[]): EnvRules[];
+/** '<env> had no rules of its own; copied them from default.' */
+export declare function seededFromDefaultNote(envName: string): string;
+/** What a surgical write kept. Empty when the scope held no targeting rules. */
+export declare function keptTargetingNote(count: number): string;
+/** What a --replace-targeting write destroyed, and where to find it again. */
+export declare function replacedTargetingNote(count: number, previousCommitSha: string): string;