primitive-admin 1.0.48 → 1.0.50

package/dist/src/lib/project-config.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Project-scoped configuration (.primitive/config.json).
+ *
+ * This module handles loading, validating, and saving the project config file
+ * that lives inside the .primitive/ directory at the project root. The config
+ * defines named environments (dev, prod, staging, etc.) with their API URLs
+ * and app IDs.
+ *
+ * Design:
+ *   - Config file: .primitive/config.json (or any ancestor directory)
+ *   - The .primitive/ directory groups the committable config and the
+ *     gitignored local state (credentials, sync data) in one place.
+ *   - Format: JSON
+ *   - Schema is versioned (currently 1). Future versions use semver-ish
+ *     caret range compatibility: we accept any config where major version
+ *     matches CURRENT_CONFIG_VERSION.
+ *   - Invalid configs throw — we do NOT silently ignore malformed files.
+ */
+/**
+ * Current schema version. Increment the major version when making
+ * backward-incompatible changes. Older configs will be rejected.
+ */
+export declare const CURRENT_CONFIG_VERSION = 1;
+/**
+ * The config file lives inside the .primitive/ directory, not at the
+ * project root. This keeps the project root clean and groups all
+ * Primitive state (config, credentials, sync data) under one directory.
+ */
+export declare const PROJECT_CONFIG_DIR = ".primitive";
+export declare const PROJECT_CONFIG_FILENAME = "config.json";
+/** Display name used in user-facing messages. */
+export declare const PROJECT_CONFIG_DISPLAY_NAME = ".primitive/config.json";
+export interface ProjectEnvironment {
+    apiUrl: string;
+    appId?: string;
+    appName?: string;
+    /** Optional notes about this environment. */
+    description?: string;
+}
+export interface ProjectConfig {
+    /** Schema version (currently 1). */
+    version: number;
+    /**
+     * Default environment name to use when --env is not specified and
+     * PRIMITIVE_ENV is unset.
+     */
+    defaultEnvironment?: string;
+    /**
+     * Named environments keyed by short name (e.g. "dev", "prod", "staging").
+     */
+    environments: Record<string, ProjectEnvironment>;
+}
+export declare class ProjectConfigError extends Error {
+    readonly path?: string;
+    constructor(message: string, path?: string);
+}
+/**
+ * Walks upward from `startDir` looking for a `.primitive/config.json` file.
+ * Returns the absolute path to the config file, or null if not found.
+ *
+ * Allows running `primitive` commands from subdirectories of a project,
+ * much like `git` walks up to find `.git`.
+ */
+export declare function findProjectConfigPath(startDir?: string): string | null;
+/**
+ * Returns the project root directory (the parent of .primitive/ that contains
+ * .primitive/config.json), or null if no project config is found.
+ *
+ * When the PRIMITIVE_PROJECT_CONFIG env var override is active, the config
+ * file may not live inside a `.primitive/` directory (e.g. in tests), so
+ * we simply go up one level from the file.
+ */
+export declare function findProjectRoot(startDir?: string): string | null;
+/**
+ * Validates a raw parsed object against the ProjectConfig schema.
+ * Throws ProjectConfigError with a helpful message on any problem.
+ */
+export declare function validateProjectConfig(raw: unknown, sourcePath?: string): ProjectConfig;
+/**
+ * Loads and validates the project config from a specific file path.
+ * Throws ProjectConfigError on I/O errors, JSON parse errors, or schema
+ * validation failures — we deliberately do NOT swallow these, because a
+ * broken config should be noisy so the user can fix it.
+ */
+export declare function loadProjectConfigFromPath(path: string): ProjectConfig;
+/**
+ * Loads the project config by searching upward from the current directory.
+ * Returns null (not an error) if no .primitive/config.json is found anywhere.
+ * Still throws ProjectConfigError if a config IS found but is invalid.
+ */
+export declare function loadProjectConfig(startDir?: string): ProjectConfig | null;
+/**
+ * Writes a project config to disk as pretty-printed JSON. Callers are
+ * responsible for ensuring the parent directory exists — this function
+ * does not try to be clever about location.
+ */
+export declare function saveProjectConfig(path: string, config: ProjectConfig): void;

package/dist/src/lib/refresh-admin-credentials.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Shared helper for refreshing the admin access token via the CLI auth API.
+ *
+ * Why this module exists:
+ *
+ *   - `ApiClient.refreshToken()` already POSTs to /admin/api/auth/refresh
+ *     before every API call when the access token is near expiry.
+ *   - `primitive token` (issue #772) now needs the same exchange so it can
+ *     auto-refresh a stale token before printing it.
+ *   - `primitive login --token-stdin` does the same POST a third time to
+ *     bootstrap credentials from a refresh token piped from another CLI.
+ *
+ * Putting the HTTP exchange + response parsing in one place keeps the
+ * response-shape contract in a single spot (server returns both `jwt` and
+ * `accessToken` — see `src/index.ts:2349-2356`) and means future server
+ * changes to that endpoint require touching exactly one CLI file.
+ *
+ * Design notes:
+ *
+ *   - This module **does not** depend on `api-client.ts`. `ApiClient` imports
+ *     it, not the other way around — that prevents the avoidable module cycle
+ *     codex flagged in the design review.
+ *   - It defines its own `RefreshError` so callers can map failures to
+ *     whatever error type (or exit code) makes sense for their surface.
+ *     `ApiClient` translates these to `ApiError`; the `token` command
+ *     translates them to an `error()` + `process.exit(1)`.
+ *   - It **does not save** the refreshed credentials. The caller decides
+ *     whether to persist (the `token` command does; `ApiClient.refreshToken`
+ *     does). Keeping persistence caller-owned matches the existing
+ *     "storage is owned by `credentials-store.ts`" convention.
+ *   - It **does not print anything**. Output (success/failure messaging) is
+ *     the caller's responsibility — important because the `token` command
+ *     must keep stdout clean for piping.
+ */
+import type { Credentials } from "../types/index.js";
+/**
+ * Reasons a refresh attempt can fail. `unauthorized` covers any HTTP non-2xx
+ * response (typically a 401 from an expired/invalid refresh token).
+ * `network` covers transport-level failures (DNS, ECONNREFUSED, etc.).
+ * `missing-refresh-token` is a precondition failure — there's no token to
+ * send.
+ */
+export type RefreshFailureKind = "missing-refresh-token" | "unauthorized" | "network";
+export declare class RefreshError extends Error {
+    kind: RefreshFailureKind;
+    statusCode?: number;
+    cause?: unknown;
+    constructor(message: string, kind: RefreshFailureKind, statusCode?: number, cause?: unknown);
+}
+/**
+ * Exchange the stored refresh token for a fresh `accessToken`. Returns a new
+ * `Credentials` object — the caller is responsible for persistence via
+ * `saveCredentials()` (or whatever storage the caller owns).
+ *
+ * Server contract: `POST {serverUrl}/admin/api/auth/refresh` with
+ *   { refreshToken: string }
+ * Response (200):
+ *   { jwt, accessToken, refreshToken, expiresAt }
+ *
+ * We accept `accessToken` as the canonical field and fall back to `jwt` for
+ * forward-compat (the server currently emits both — see issue #772 codex
+ * cleanup #3). Login's legacy `data.token` form is dropped — no server
+ * version that's still in support emits that field.
+ */
+export declare function refreshAdminCredentials(credentials: Credentials): Promise<Credentials>;

package/dist/src/lib/resolve-platform.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Pure resolution of the target platform for `primitive init`.
+ *
+ * Background (issue #1009): `primitive init` must become platform-aware. The
+ * commander `-p, --platform` option no longer carries a `"web"` default, so an
+ * omitted flag is `undefined` and distinguishable from an explicit
+ * `--platform web`. Resolution follows a 4-case interactivity contract:
+ *
+ *   (a) explicit `--platform` flag set        -> use it (never prompt)
+ *   (b) init-config TOML present (configPlatform may be set) -> use config
+ *       value, else fall back to "web" (never prompt)
+ *   (c) interactive TTY, no flag, no config    -> prompt with `select`
+ *   (d) non-TTY, no flag, no config            -> fall back to "web" WITHOUT
+ *       hanging and WITHOUT the `ERR_USE_AFTER_CLOSE` crash that
+ *       `@inquirer/prompts` `select` throws on a closed/piped stdin
+ *       (same hazard family hardened in #972/#999 — see `confirm-prompt.ts`).
+ *
+ * Extracting the decision into a pure function (with injectable `isTTY` /
+ * `promptFn`, mirroring `confirm-prompt.ts`) makes the otherwise
+ * terminal-dependent interactivity contract unit-testable.
+ */
+export type Platform = "web" | "ios";
+/** Prompt thunk returning the chosen platform. Injectable for testing. */
+export type PlatformPromptFn = () => Promise<Platform>;
+export interface ResolvePlatformOptions {
+    /** Value of the explicit `--platform` flag, or `undefined` when omitted. */
+    flag?: Platform;
+    /** `platform` key from a loaded `.primitive-init.toml`, if a config is present. */
+    configPlatform?: Platform;
+    /**
+     * Whether a non-interactive init-config file is in effect. When `true`, the
+     * prompt is skipped entirely (case b) regardless of TTY.
+     */
+    hasConfig: boolean;
+    /** Whether stdin is an interactive TTY. Inject `false` to exercise case (d). */
+    isTTY: boolean;
+    /** Prompt function used only in the interactive case (c). */
+    promptFn: PlatformPromptFn;
+}
+/**
+ * Resolve the target platform per the 4-case interactivity contract above.
+ *
+ * @returns the resolved platform (`"web"` or `"ios"`).
+ */
+export declare function resolvePlatform(options: ResolvePlatformOptions): Promise<Platform>;

package/dist/src/lib/resolve-platform.js

@@ -0,0 +1,43 @@
+/**
+ * Pure resolution of the target platform for `primitive init`.
+ *
+ * Background (issue #1009): `primitive init` must become platform-aware. The
+ * commander `-p, --platform` option no longer carries a `"web"` default, so an
+ * omitted flag is `undefined` and distinguishable from an explicit
+ * `--platform web`. Resolution follows a 4-case interactivity contract:
+ *
+ *   (a) explicit `--platform` flag set        -> use it (never prompt)
+ *   (b) init-config TOML present (configPlatform may be set) -> use config
+ *       value, else fall back to "web" (never prompt)
+ *   (c) interactive TTY, no flag, no config    -> prompt with `select`
+ *   (d) non-TTY, no flag, no config            -> fall back to "web" WITHOUT
+ *       hanging and WITHOUT the `ERR_USE_AFTER_CLOSE` crash that
+ *       `@inquirer/prompts` `select` throws on a closed/piped stdin
+ *       (same hazard family hardened in #972/#999 — see `confirm-prompt.ts`).
+ *
+ * Extracting the decision into a pure function (with injectable `isTTY` /
+ * `promptFn`, mirroring `confirm-prompt.ts`) makes the otherwise
+ * terminal-dependent interactivity contract unit-testable.
+ */
+/**
+ * Resolve the target platform per the 4-case interactivity contract above.
+ *
+ * @returns the resolved platform (`"web"` or `"ios"`).
+ */
+export async function resolvePlatform(options) {
+    // (a) explicit flag wins, no prompt.
+    if (options.flag !== undefined) {
+        return options.flag;
+    }
+    // (b) non-interactive config present: use its platform or default to web.
+    if (options.hasConfig) {
+        return options.configPlatform ?? "web";
+    }
+    // (c) interactive TTY, no flag, no config: prompt.
+    if (options.isTTY) {
+        return options.promptFn();
+    }
+    // (d) non-TTY, no flag, no config: never prompt; fall back to web.
+    return "web";
+}
+//# sourceMappingURL=resolve-platform.js.map

package/dist/src/lib/resolve-platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-platform.js","sourceRoot":"","sources":["../../../src/lib/resolve-platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAuBH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAA+B;IAE/B,qCAAqC;IACrC,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,OAAO,CAAC,IAAI,CAAC;IACtB,CAAC;IAED,0EAA0E;IAC1E,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACtB,OAAO,OAAO,CAAC,cAAc,IAAI,KAAK,CAAC;IACzC,CAAC;IAED,mDAAmD;IACnD,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;IAC5B,CAAC;IAED,mEAAmE;IACnE,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/src/lib/skill-installer.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Returns true if the skill is currently installed.
+ */
+export declare function isSkillInstalled(): boolean;
+/**
+ * Auto-update an already-installed skill if a newer version is bundled.
+ * Called after command execution for non-init, non-skill commands.
+ * If the skill is not installed, shows a non-blocking hint instead.
+ * Never throws — fails silently like version-check.
+ */
+export declare function checkSkillStatus(): Promise<void>;
+/**
+ * Explicitly install or reinstall the skill. Shows output.
+ */
+export declare function installSkillExplicit(): boolean;
+/**
+ * Uninstall the skill.
+ */
+export declare function uninstallSkill(): boolean;
+/**
+ * Show current skill installation status.
+ */
+export declare function skillStatus(): void;

package/dist/src/lib/snapshots.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Sync snapshots — point-in-time backups of a sync directory taken before a
+ * destructive `sync pull` overwrites local TOML state (issue #578, Phase 1).
+ *
+ * A snapshot is a full recursive copy of the live sync tree (including
+ * `.primitive-sync.json`, the content-hash baseline) into a timestamped slot
+ * under the snapshots root:
+ *
+ *   <snapshotsRoot>/<YYYY-MM-DDTHH-MM-SS>/
+ *       <full pre-pull copy of the sync tree, incl. .primitive-sync.json>
+ *       .snapshot-complete        # integrity marker, written LAST
+ *       .audit-id                 # ULID cross-link (Phase 2; absent in P1)
+ *
+ * The `.snapshot-complete` marker is written last so a partial/interrupted
+ * copy is detectable: `restoreSnapshot` refuses any snapshot missing it.
+ *
+ * Snapshots fail LOUD — `createSnapshot` throws if it can't write a complete
+ * snapshot. The caller (sync pull) aborts before touching any local file so we
+ * never perform a destructive pull without a recoverable backup.
+ *
+ * Restore is staged-then-swapped: the snapshot is materialized into a sibling
+ * temp dir, then the live `configDir` is atomically replaced, so a mid-restore
+ * crash never leaves a half-written tree.
+ */
+/** Marker file written LAST inside a snapshot to prove it completed. */
+export declare const SNAPSHOT_COMPLETE_MARKER = ".snapshot-complete";
+/** Cross-link to the audit entry that produced the snapshot (Phase 2). */
+export declare const SNAPSHOT_AUDIT_ID_MARKER = ".audit-id";
+export interface SnapshotResult {
+    /** Snapshot id — the timestamp directory name (YYYY-MM-DDTHH-MM-SS). */
+    id: string;
+    /** Absolute path to the snapshot directory. */
+    path: string;
+}
+export interface SnapshotInfo {
+    /** Snapshot id — the timestamp directory name. */
+    id: string;
+    /** Absolute path to the snapshot directory. */
+    path: string;
+    /** Whether the `.snapshot-complete` marker is present. */
+    complete: boolean;
+    /** The audit entry id this snapshot is cross-linked to, if any. */
+    auditId: string | null;
+    /** Creation time (from the directory mtime). */
+    createdAt: Date;
+}
+/**
+ * Snapshot the current `syncDir` into a new timestamped slot under
+ * `snapshotsRoot`. Returns the created snapshot, or `null` when there's
+ * nothing to back up (missing/empty `syncDir`).
+ *
+ * Fails LOUD: throws if the copy or marker write fails. The partial snapshot
+ * dir is best-effort cleaned up before rethrowing so a failed snapshot never
+ * leaves a marker-less husk behind.
+ */
+export declare function createSnapshot(syncDir: string, snapshotsRoot: string, opts?: {
+    auditId?: string;
+    now?: Date;
+}): SnapshotResult | null;
+/**
+ * List snapshots under `snapshotsRoot`, newest-first. Returns an empty array
+ * if the root doesn't exist. Each entry reports whether it's complete and any
+ * cross-linked audit id.
+ */
+export declare function listSnapshots(snapshotsRoot: string): SnapshotInfo[];
+/**
+ * Resolve a snapshot by id within `snapshotsRoot`. Accepts either the full
+ * timestamp directory name OR a unique prefix of at least `minPrefix`
+ * characters (default 8). Returns the matching snapshot, or throws a clear
+ * error on no-match / ambiguous-prefix.
+ *
+ * When `id` is omitted, resolves to the most recent COMPLETE snapshot.
+ */
+export declare function resolveSnapshot(snapshotsRoot: string, id: string | undefined, minPrefix?: number): SnapshotInfo;
+/**
+ * Restore a snapshot into `syncDir`, replacing whatever is there.
+ *
+ * Refuses to restore a snapshot missing the `.snapshot-complete` marker
+ * (partial/corrupted snapshot). The internal marker files (`.snapshot-complete`,
+ * `.audit-id`) are NOT copied into the restored tree.
+ *
+ * Staged-then-swapped: the snapshot is materialized into a sibling temp dir,
+ * then `syncDir` is atomically replaced, so a mid-restore crash never leaves a
+ * half-written tree.
+ *
+ * `opts.preserveDir` names a directory (the snapshots root) that lives INSIDE
+ * `syncDir` and must survive the full-tree swap — the Fork-4 legacy `--dir`
+ * case, where backups sit at `<syncDir>/.snapshots/`. Without preserving it,
+ * the swap would wipe the user's entire snapshot history on restore.
+ */
+export declare function restoreSnapshot(snapshotPath: string, syncDir: string, opts?: {
+    preserveDir?: string;
+}): void;
+/**
+ * Prune snapshots older than `retentionDays` from `snapshotsRoot`. Only the
+ * given slot is touched (cross-slot retention is independent — each slot has
+ * its own snapshots root). No-op if the root doesn't exist.
+ */
+export declare function pruneSnapshots(snapshotsRoot: string, retentionDays?: number): void;