primitive-admin 1.0.61 → 1.0.62

package/dist/src/commands/sync-app-settings.d.ts

@@ -1,102 +1,123 @@
 /**
- * Shared app-settings sync helpers (issue #1033, Phase 2).
+ * Shared app-settings helpers (issue #1033, Phase 2; narrowed by #2645).
  *
  * The descriptor-driven `app.toml` round-trip (issue #1033, Phase 1) was born
- * inside the big `sync pull` / `sync push` command flow. Phase 2 lifts the
- * app-settings-specific pieces here so BOTH surfaces drive them:
+ * inside the big `config pull` / `config push` command flow. Phase 2 lifted the
+ * app-settings-specific pieces here so both surfaces could drive them. #2645
+ * then removed the second surface: `app.toml` is authored like every other
+ * configuration file and applied by `config push`, so what is left here is what
+ * `sync` calls (`serializeAppSettings`, `writePulledAppSettings`,
+ * `collectAppSettingsPushErrors`, `diffAppSettings` for `config diff --only app`)
+ * plus the one thing the file cannot answer — `renderAppSettings`, the
+ * server-effective view behind `primitive apps get` (#2759).
  *
- *   - `sync pull` / `sync push` call the low-level helpers
- *     (`serializeAppSettings`, `collectAppSettingsPushErrors`) — behavior
- *     unchanged from Phase 1.
- *   - the new `primitive settings show|pull|push|diff` command
- *     (`cli/src/commands/settings.ts`) calls the higher-level orchestrators
- *     (`pullAppSettings`, `pushAppSettings`, `diffAppSettings`, `showAppSettings`).
+ * #2880 added the comparison the whole epic is about — `appSettingsFieldDiffs`,
+ * `hashAppSettingsForDiff` and `appSettingsNameExcluded` — and removed the last
+ * caller of the retired byte-hash/present-only rule (the `settings push`
+ * orchestrator #2645 had already unhooked). `app.toml` is now compared field by
+ * field against live state by both commands, over the full writable descriptor
+ * set, and applied as the whole truth.
  *
- * Both directions share the same `app.toml`, the same field descriptor
- * (`cli/src/lib/app-settings-descriptor.ts`), and the same single
- * `entities.app.contentHash` sync-state entry, so `settings push` then
- * `sync push` (or the reverse) is idempotent — the second one skips on the
- * unchanged hash.
- *
- * `googleClientSecret` never leaves the server through here: pull omits it,
- * push errors on it (pointing at `primitive apps update --google-client-secret`),
- * and `settings show` redacts it in both the rendered and `--json` views.
+ * Google is a typed client map here (#2891): `googleClients` renders as
+ * `[auth.google.clients.<type>]`, and each entry's `clientSecret` holds a whole
+ * `{{secrets.KEY}}` reference, not the secret itself, so the map pulls, pushes,
+ * diffs and shows like any other setting. The secrets' values live only in the
+ * app secret store (`primitive secrets set`).
  */
 import type { ApiClient } from "../lib/api-client.js";
 import { type AppSettingSection } from "../lib/app-settings-descriptor.js";
+import type { SyncState } from "../types/index.js";
 /** The app-settings file name inside a sync directory. */
 export declare const APP_TOML_FILENAME = "app.toml";
 /** Absolute path to `app.toml` inside a sync directory. */
 export declare function appTomlPath(configDir: string): string;
 /**
  * Serialize server settings into the `app.toml` string (pull direction).
- * Descriptor-driven; `googleClientSecret` is never emitted. This is the single
- * serializer both `sync pull` and `settings pull` use.
+ * Descriptor-driven; this is the single serializer every pull path uses.
  */
 export declare function serializeAppSettings(settings: any): string;
 /**
  * Write `app.toml` from server settings and return its content hash. Shared by
- * `sync pull` and `settings pull` so the two produce byte-identical files and
- * the same hash.
+ * `config pull` (whole-tree and `--only app`), so the file and the hash have one
+ * producer.
  */
 export declare function writeAppSettingsToml(configDir: string, settings: any): string;
 /**
- * Validate a parsed `app.toml` for push and return the fatal errors (a
- * hand-added secret key, a type mismatch). An empty array means the push may
- * proceed. Warnings (unrecognized keys) are intentionally not returned here —
- * the caller surfaces those at apply time. Shared by the `sync push` preflight
- * and `settings push`.
+ * Validate a parsed `app.toml` for push and return the fatal errors (a type
+ * mismatch, an unrecognized or retired key, a missing required key). An empty
+ * array means the push may proceed. Warnings (advisory notes) are intentionally
+ * not returned here — the caller surfaces those at apply time.
+ *
+ * ONE validator, run by `config push`'s preflight AND by `config diff` (#2880
+ * criterion 1): a file diff calls Synced is a file push accepts, and a file
+ * push refuses is named by diff with the identical message.
  */
 export declare function collectAppSettingsPushErrors(tomlData: Record<string, any>, options?: {
     isCrossAppPush?: boolean;
+    excludeName?: boolean;
 }): string[];
-/** Placeholder shown in `settings show` in place of any secret field value. */
-export declare const REDACTED_PLACEHOLDER = "[redacted \u2014 set via: primitive apps update <appId> --google-client-secret]";
 /**
- * Return a copy of the server settings with every secret descriptor field
- * (currently `googleClientSecret`) redacted when a secret is stored. Used for
- * BOTH the rendered and `--json` outputs of `settings show` so the real secret
- * never leaves the server through this command (codex design-review concern #2).
+ * Render server-effective settings grouped by `app.toml` section — the view
+ * `apps get` prints (issue #2759; it was `apps get` before the fold).
  *
- * A secret counts as stored when either:
- *  - the server sent a truthy raw value — a server older than #1603, which
- *    still returns `googleClientSecret` on GET; or
- *  - the companion `<field>Set` boolean is true — #1603 made the secret
- *    write-only, so `GET /settings` omits the raw value entirely and reports
- *    `googleClientSecretSet` instead. Without this branch a configured secret
- *    renders as "(not set)", indistinguishable from an unconfigured one.
+ * Descriptor-driven on purpose: a new setting appears here by being declared,
+ * where the hand-curated block `apps get` used to print showed whichever
+ * fields somebody remembered to add.
  *
- * When nothing is stored the field is left untouched, so it renders as
- * "(not set)" — which is then accurate.
- */
-export declare function redactSecretFields(settings: Record<string, any>): Record<string, any>;
-/**
- * `settings show` — render the current server-effective settings grouped by
- * `app.toml` section, with `googleClientSecret` redacted. `--json` emits the
- * full (redacted) server response.
+ * Nothing is redacted (#2256, #2891): the only credential-shaped settings are
+ * the per-entry `clientSecret`s inside `googleClients`, and each is a whole
+ * `{{secrets.KEY}}` reference rather than the secret itself — so printing one
+ * tells the operator which secret is in use rather than leaking one. There is
+ * no withheld state left to explain.
+ *
+ * Takes settings rather than a client, and never exits: `apps get` fetches the
+ * app and its settings together and tolerates a settings fetch it is not
+ * allowed to make, so failure handling belongs at the call site.
  */
-export declare function showAppSettings(client: ApiClient, appId: string, options?: {
-    json?: boolean;
-}): Promise<void>;
+export declare function renderAppSettings(settings: any): void;
 /**
- * `settings pull` — fetch the server settings, write `app.toml`, and stamp the
- * shared `entities.app.contentHash`. Same file and hash as `sync pull`.
+ * Write the pulled `app.toml`.
+ *
+ * The file carries EVERY writable setting as of #2891 — the server withholds
+ * nothing, so there is no longer a class of value the pull has to warn about
+ * being absent (#2307's warning went with the withholding layer). `config pull`
+ * calls this for `app.toml`, whether the pull is whole-tree or `--only app`.
  */
-export declare function pullAppSettings(client: ApiClient, appId: string, configDir: string, options?: {
-    json?: boolean;
-}): Promise<void>;
+export declare function writePulledAppSettings(configDir: string, settings: any, options?: {
+    log?: (message: string) => void;
+}): {
+    path: string;
+    contentHash: string;
+};
 /**
- * `settings push` — read `app.toml`, validate (abort before any PUT on a secret
- * key or a type mismatch), skip when unchanged since the last sync unless
- * `--force`, then apply via `PUT /settings` and re-stamp the shared content
- * hash. Cross-app pushes (state's app differs from the target) always apply and
- * strip `name`, matching `sync push`.
+ * Whether `[app].name` is out of BOTH the comparison and the payload right now
+ * (#2880 DSO-001) — the cross-app rule, shared so diff and push cannot disagree.
+ *
+ * A cross-app push (the sync state belongs to a different app) applies the file
+ * to the target with `name` excluded, so it never renames the target, and it
+ * RECORDS the file's name in `entities.app.excludedName` with the baseline
+ * hashed the same way. While that record stands and the file still states that
+ * name, the field stays excluded: the target keeps its own name and no phantom
+ * difference appears.
+ *
+ * A file name that DIFFERS from the recorded one is, by construction, a local
+ * name edit — the operator changed the line — so the exclusion lifts, the name
+ * goes into the payload, and the baseline is restamped with `name` from the
+ * server's returned record. It cannot be discovered by comparison instead:
+ * `classifyPushChange` only answers `local-edited` when the remote hash equals
+ * the baseline, and a baseline stamped without `name` matches neither side once
+ * `name` re-enters, so every post-cross-app rename would report `both-changed`.
  */
-export declare function pushAppSettings(client: ApiClient, appId: string, configDir: string, options?: {
-    json?: boolean;
-    force?: boolean;
-    dryRun?: boolean;
-}): Promise<void>;
+export declare function appSettingsNameExcluded(input: {
+    /** The sync state belongs to a different app than the one being written. */
+    isCrossAppPush: boolean;
+    /** `entities.app.excludedName` — the name a prior cross-app push left alone. */
+    recordedExcludedName?: unknown;
+    /** The `[app].name` the local file states right now. */
+    fileName?: unknown;
+}): boolean;
+/** `appSettingsNameExcluded` for a caller holding the loaded state (diff). */
+export declare function appSettingsNameExcludedForState(state: SyncState | null, appId: string, tomlData: Record<string, any> | null | undefined): boolean;
 export interface AppSettingsFieldDiff {
     field: string;
     section: AppSettingSection;
@@ -105,10 +126,32 @@ export interface AppSettingsFieldDiff {
     remote: unknown;
 }
 /**
- * `settings diff` — report per-field differences between the local `app.toml`
- * push payload and the current server settings. Only keys present in the TOML
- * are compared, so a server value that equals a descriptor default (and is
- * therefore omitted from `app.toml`) is never flagged as a spurious difference.
+ * The fields the local `app.toml` and the live settings disagree on (#2880).
+ *
+ * Compared over the FULL writable descriptor set, not just the keys the file
+ * carries: `app.toml` is the whole truth, so a key the file omits is not "no
+ * opinion", it is the absent-value the push will send. Both sides run through
+ * `projectAppSettingsForComparison`, which applies the same canonicalization
+ * and the same `whenSet`-empty flattening to each — so a pulled file compares
+ * equal to the server it was pulled from, and a deleted key shows as the clear
+ * push would apply.
+ *
+ * One helper, three callers: `config diff --only app`'s per-field output, the
+ * app-settings row in the full `config diff`, and the push gate.
+ */
+export declare function appSettingsFieldDiffs(localSettings: Record<string, any>, remoteSettings: Record<string, any> | null | undefined, options?: {
+    excludeName?: boolean;
+}): AppSettingsFieldDiff[];
+/**
+ * The comparator's hash of one side's app settings — the push gate's
+ * `localHash`/`remoteHash`, and the `entities.app.semanticHash` baseline
+ * stamped once the two agree (#2880 criterion 6).
+ */
+export declare function hashAppSettingsForDiff(settings: Record<string, any> | null | undefined, options?: {
+    excludeName?: boolean;
+}): string;
+/**
+ * `config diff --only app` — the per-field report, over the full writable set.
  */
 export declare function diffAppSettings(client: ApiClient, appId: string, configDir: string, options?: {
     json?: boolean;