primitive-admin 1.0.61 → 1.0.63

package/dist/src/commands/sessions.js

@@ -1,6 +1,8 @@
+import { Option } from "commander";
 import { ApiClient } from "../lib/api-client.js";
 import { resolveAppId } from "../lib/config.js";
 import { error, info, formatTable, formatDate, json, } from "../lib/output.js";
+import { resolveUserSelector } from "../lib/user-selector.js";
 export function registerSessionsCommands(program) {
     const sessions = program
         .command("sessions")
@@ -11,19 +13,29 @@ expired — an expired session that has not yet been swept still appears, with
 ACTIVE = false. Authentication tokens are never returned.
 
 Examples:
-  $ primitive sessions list --user 01HXY...
-  $ primitive sessions list --user 01HXY... --limit 50
-  $ primitive sessions list --user 01HXY... --json
+  $ primitive sessions list --user-id 01HXY...
+  $ primitive sessions list --user-id 01HXY... --limit 50
+  $ primitive sessions list --user-id 01HXY... --json
 `);
     sessions
         .command("list")
         .description("List a user's sessions")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .requiredOption("--user <user-id>", "List sessions for this user")
+        // `--user-id` is canonical (#2357). It cannot be a `requiredOption` any
+        // more, because the deprecated `--user` alias also satisfies the
+        // requirement — commander would reject `--user 01H…` before the alias
+        // resolution runs. The explicit check below keeps the same contract.
+        .option("--user-id <user-id>", "List sessions for this user")
+        .addOption(new Option("--user <user-id>", "Deprecated alias of --user-id").hideHelp())
         .option("--limit <n>", "Maximum rows to return (default 25, max 100)")
         .option("--cursor <cursor>", "Pagination cursor from a previous page")
         .option("--json", "Output as JSON")
         .action(async (options) => {
+        const userId = resolveUserSelector(options, "sessions list");
+        if (!userId) {
+            error("required option '--user-id <user-id>' not specified");
+            process.exit(1);
+        }
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         const limit = options.limit ? Number(options.limit) : undefined;
@@ -33,7 +45,7 @@ Examples:
             process.exit(1);
         }
         try {
-            const { items, nextCursor } = await client.listSessions(resolvedAppId, options.user, { limit, cursor: options.cursor });
+            const { items, nextCursor } = await client.listSessions(resolvedAppId, userId, { limit, cursor: options.cursor });
             if (options.json) {
                 json({ items, nextCursor });
                 return;

package/dist/src/commands/sessions.js.map

@@ -1 +1 @@
-{"version":3,"file":"sessions.js","sourceRoot":"","sources":["../../../src/commands/sessions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sessions.js","sourceRoot":"","sources":["../../../src/commands/sessions.ts"],"names":[],"mappings":"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"}

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;