primitive-admin 1.0.49 → 1.0.50

package/dist/src/lib/snapshots.js

@@ -0,0 +1,357 @@
+/**
+ * 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.
+ */
+import { existsSync, readdirSync, statSync, writeFileSync, readFileSync, cpSync, rmSync, renameSync, mkdirSync, mkdtempSync, } from "fs";
+import { join, dirname, resolve, relative, isAbsolute } from "path";
+/**
+ * Returns true if `child` is `parent` or lives somewhere beneath it. Used to
+ * detect the legacy `--dir` case where the snapshots root sits INSIDE the sync
+ * tree (`<userDir>/.snapshots/`) — we must not copy that subtree into the
+ * snapshot, or `cpSync` recurses into itself.
+ */
+function isInside(parent, child) {
+    const rel = relative(resolve(parent), resolve(child));
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+/** Marker file written LAST inside a snapshot to prove it completed. */
+export const SNAPSHOT_COMPLETE_MARKER = ".snapshot-complete";
+/** Cross-link to the audit entry that produced the snapshot (Phase 2). */
+export const SNAPSHOT_AUDIT_ID_MARKER = ".audit-id";
+/**
+ * Produce the timestamp directory name for a snapshot, e.g.
+ * `2026-06-01T17-42-18`. Colons (illegal on Windows, awkward everywhere) are
+ * replaced with hyphens; milliseconds and the trailing `Z` are dropped.
+ */
+function snapshotTimestamp(now = new Date()) {
+    // 2026-06-01T17:42:18.401Z -> 2026-06-01T17-42-18
+    return now.toISOString().replace(/\.\d+Z$/, "").replace(/:/g, "-");
+}
+/**
+ * Returns true if `dir` exists and contains at least one entry. A fresh
+ * project (no prior sync dir, or an empty one) has nothing to back up.
+ */
+function dirHasContent(dir) {
+    if (!existsSync(dir))
+        return false;
+    try {
+        return readdirSync(dir).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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 function createSnapshot(syncDir, snapshotsRoot, opts = {}) {
+    if (!dirHasContent(syncDir)) {
+        return null;
+    }
+    const id = snapshotTimestamp(opts.now);
+    const dest = join(snapshotsRoot, id);
+    // Guard against an id collision (two pulls within the same second). Append a
+    // numeric suffix until we find a free slot so a rapid second pull can't
+    // clobber the first snapshot.
+    let finalId = id;
+    let finalDest = dest;
+    let suffix = 1;
+    while (existsSync(finalDest)) {
+        finalId = `${id}-${suffix}`;
+        finalDest = join(snapshotsRoot, finalId);
+        suffix += 1;
+    }
+    // Fork 4: under legacy `--dir`, the snapshots root lives INSIDE the sync
+    // tree (`<userDir>/.snapshots/`). Node's cpSync refuses to copy a directory
+    // into its own subtree (ERR_FS_CP_EINVAL) even with a filter, so in that
+    // case we stage the copy into an external temp dir (excluding the backups
+    // subtree) and then move it into place.
+    const rootIsInside = isInside(syncDir, snapshotsRoot);
+    const snapshotsRootResolved = resolve(snapshotsRoot);
+    const filter = rootIsInside
+        ? (src) => !isInside(snapshotsRootResolved, src)
+        : undefined;
+    let externalStage = null;
+    try {
+        mkdirSync(snapshotsRoot, { recursive: true });
+        if (rootIsInside) {
+            // Copy to a sibling of syncDir first (outside the sync tree, so no
+            // self-recursion), then move into the inside-the-tree slot. Staging in
+            // the parent keeps the move same-filesystem (avoids cross-device EXDEV
+            // that a tmpdir stage could hit).
+            const parent = dirname(resolve(syncDir));
+            mkdirSync(parent, { recursive: true });
+            externalStage = mkdtempSync(join(parent, ".primitive-snapshot-stage-"));
+            const stageTree = join(externalStage, "tree");
+            cpSync(syncDir, stageTree, {
+                recursive: true,
+                dereference: false,
+                ...(filter ? { filter } : {}),
+            });
+            renameSync(stageTree, finalDest);
+        }
+        else {
+            // Full recursive copy. `dereference: false` keeps symlinks from being
+            // silently followed (edge case: symlinks inside the sync tree).
+            cpSync(syncDir, finalDest, { recursive: true, dereference: false });
+        }
+        if (opts.auditId) {
+            writeFileSync(join(finalDest, SNAPSHOT_AUDIT_ID_MARKER), opts.auditId);
+        }
+        // Integrity marker written LAST — its presence proves the copy finished.
+        writeFileSync(join(finalDest, SNAPSHOT_COMPLETE_MARKER), new Date().toISOString());
+    }
+    catch (err) {
+        // Best-effort cleanup of the partial snapshot so we don't leave an
+        // incomplete (marker-less) directory around.
+        try {
+            rmSync(finalDest, { recursive: true, force: true });
+        }
+        catch {
+            // ignore cleanup failure
+        }
+        throw err;
+    }
+    finally {
+        if (externalStage) {
+            try {
+                rmSync(externalStage, { recursive: true, force: true });
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    return { id: finalId, path: finalDest };
+}
+/**
+ * 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 function listSnapshots(snapshotsRoot) {
+    if (!existsSync(snapshotsRoot))
+        return [];
+    let names;
+    try {
+        names = readdirSync(snapshotsRoot);
+    }
+    catch {
+        return [];
+    }
+    const infos = [];
+    for (const name of names) {
+        const path = join(snapshotsRoot, name);
+        let stat;
+        try {
+            stat = statSync(path);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isDirectory())
+            continue;
+        const complete = existsSync(join(path, SNAPSHOT_COMPLETE_MARKER));
+        let auditId = null;
+        const auditPath = join(path, SNAPSHOT_AUDIT_ID_MARKER);
+        if (existsSync(auditPath)) {
+            try {
+                auditId = readFileSync(auditPath, "utf-8").trim() || null;
+            }
+            catch {
+                auditId = null;
+            }
+        }
+        infos.push({ id: name, path, complete, auditId, createdAt: stat.mtime });
+    }
+    // Newest first. The id is a sortable timestamp string, so a reverse string
+    // sort matches chronological order (and stays correct for the `-N` suffixed
+    // collision variants within the same second).
+    infos.sort((a, b) => (a.id < b.id ? 1 : a.id > b.id ? -1 : 0));
+    return infos;
+}
+/**
+ * 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 function resolveSnapshot(snapshotsRoot, id, minPrefix = 8) {
+    const all = listSnapshots(snapshotsRoot);
+    if (all.length === 0) {
+        throw new Error(`No snapshots found in ${snapshotsRoot}`);
+    }
+    if (!id) {
+        const mostRecentComplete = all.find((s) => s.complete);
+        if (!mostRecentComplete) {
+            throw new Error(`No complete snapshots found in ${snapshotsRoot} (all are missing the ${SNAPSHOT_COMPLETE_MARKER} marker).`);
+        }
+        return mostRecentComplete;
+    }
+    // Exact match wins.
+    const exact = all.find((s) => s.id === id);
+    if (exact)
+        return exact;
+    // Prefix match (must be unique and >= minPrefix chars).
+    if (id.length < minPrefix) {
+        throw new Error(`Snapshot id "${id}" is too short — provide at least ${minPrefix} characters or the full timestamp.`);
+    }
+    const matches = all.filter((s) => s.id.startsWith(id));
+    if (matches.length === 0) {
+        throw new Error(`No snapshot matches "${id}" in ${snapshotsRoot}`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`Snapshot prefix "${id}" is ambiguous (${matches.length} matches: ${matches
+            .map((m) => m.id)
+            .join(", ")}). Provide more characters.`);
+    }
+    return matches[0];
+}
+/**
+ * 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 function restoreSnapshot(snapshotPath, syncDir, opts = {}) {
+    if (!existsSync(snapshotPath)) {
+        throw new Error(`Snapshot not found: ${snapshotPath}`);
+    }
+    if (!existsSync(join(snapshotPath, SNAPSHOT_COMPLETE_MARKER))) {
+        throw new Error(`Refusing to restore: snapshot ${snapshotPath} is missing the ${SNAPSHOT_COMPLETE_MARKER} marker (partial/corrupted snapshot).`);
+    }
+    const parent = dirname(syncDir);
+    mkdirSync(parent, { recursive: true });
+    const unique = `${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
+    const stageDir = join(parent, `.primitive-restore-stage-${unique}`);
+    const oldDir = join(parent, `.primitive-restore-old-${unique}`);
+    // Determine whether a backups dir living inside syncDir needs preserving.
+    const preserve = opts.preserveDir &&
+        isInside(syncDir, opts.preserveDir) &&
+        !isInside(snapshotPath, opts.preserveDir) // don't preserve a dir that's part of the snapshot
+        ? resolve(opts.preserveDir)
+        : null;
+    const preserveStash = preserve
+        ? join(parent, `.primitive-restore-keep-${unique}`)
+        : null;
+    try {
+        // Materialize the snapshot into the staging dir.
+        cpSync(snapshotPath, stageDir, { recursive: true, dereference: false });
+        // Drop the snapshot-internal marker files from the restored tree.
+        for (const marker of [SNAPSHOT_COMPLETE_MARKER, SNAPSHOT_AUDIT_ID_MARKER]) {
+            const markerPath = join(stageDir, marker);
+            if (existsSync(markerPath)) {
+                rmSync(markerPath, { force: true });
+            }
+        }
+        // Atomic-ish swap: move the live dir aside, move staging into place, then
+        // delete the old dir. Same-filesystem renames are atomic.
+        if (existsSync(syncDir)) {
+            renameSync(syncDir, oldDir);
+        }
+        try {
+            renameSync(stageDir, syncDir);
+        }
+        catch (err) {
+            // Swap failed — try to roll the original back so we never leave the
+            // user with no sync dir at all.
+            if (existsSync(oldDir) && !existsSync(syncDir)) {
+                try {
+                    renameSync(oldDir, syncDir);
+                }
+                catch {
+                    // ignore rollback failure; original error is more useful
+                }
+            }
+            throw err;
+        }
+        // Re-attach the preserved backups dir (Fork-4 `--dir` mode) into the
+        // freshly-restored tree, pulling it out of the displaced original.
+        if (preserve && preserveStash) {
+            const rel = relative(resolve(syncDir), preserve);
+            const fromOld = join(oldDir, rel);
+            const intoNew = join(syncDir, rel);
+            if (existsSync(fromOld) && !existsSync(intoNew)) {
+                mkdirSync(dirname(intoNew), { recursive: true });
+                renameSync(fromOld, intoNew);
+            }
+        }
+        // Success — remove the displaced original.
+        if (existsSync(oldDir)) {
+            rmSync(oldDir, { recursive: true, force: true });
+        }
+    }
+    finally {
+        // Clean up any leftover staging/old/stash dirs on failure.
+        for (const dir of [stageDir, oldDir, preserveStash].filter((d) => Boolean(d))) {
+            if (existsSync(dir)) {
+                try {
+                    rmSync(dir, { recursive: true, force: true });
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+    }
+}
+/**
+ * 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 function pruneSnapshots(snapshotsRoot, retentionDays = 28) {
+    if (!existsSync(snapshotsRoot))
+        return;
+    const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
+    for (const info of listSnapshots(snapshotsRoot)) {
+        if (info.createdAt.getTime() < cutoff) {
+            try {
+                rmSync(info.path, { recursive: true, force: true });
+            }
+            catch {
+                // Best-effort prune — a failure to delete one stale snapshot must not
+                // abort the pull that triggered the prune.
+            }
+        }
+    }
+}
+//# sourceMappingURL=snapshots.js.map

package/dist/src/lib/snapshots.js.map

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

package/dist/src/lib/sync-paths.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Sync data path resolution.
+ *
+ * Per issue #373, sync state is scoped by environment AND by app:
+ *
+ *   <projectRoot>/.primitive/sync/<env>/<appId>/
+ *
+ * This ensures that switching environments (dev -> prod) or apps never
+ * clobbers sync state from another slot. Push to dev and then to prod
+ * see independent "last synced" pointers, so prod won't falsely believe
+ * dev's changes are already in sync.
+ *
+ * When the user still passes `--dir <path>` (the legacy flag) we honor
+ * it and store sync state inside that directory, same as before. This
+ * keeps pre-project-config workflows working.
+ */
+export interface ResolveSyncDirOptions {
+    /** The resolved app ID for this sync operation. */
+    appId: string;
+    /**
+     * If the user passed `--dir <path>` on the command line, forward it
+     * here. Explicit user input always wins.
+     */
+    userDir?: string;
+}
+/**
+ * Returns the directory that should hold TOML files + sync state for the
+ * current sync operation.
+ *
+ * Resolution order:
+ *   1. If userDir is set, return it as-is (legacy behavior).
+ *   2. If we're in project mode, return
+ *      <projectRoot>/.primitive/sync/<env>/<appId>
+ *   3. Otherwise fall back to "./config" (the old default).
+ */
+export declare function resolveSyncDir(options: ResolveSyncDirOptions): string;
+/**
+ * Returns the snapshot-backups root for the slot a given sync operation
+ * belongs to (issue #578, Phase 1). Snapshots reuse the SAME resolution chain
+ * as `resolveSyncDir` (the resolved `ResolvedEnvironment` + `safeEnv()`), so
+ * the backup tree can never drift from the live sync tree — there is no
+ * parallel `{projectRoot, env, appId}` mini-model.
+ *
+ * Resolution order mirrors `resolveSyncDir`:
+ *   1. If userDir (legacy `--dir`) is set, snapshots live in a sibling
+ *      `<userDir>/.snapshots/` so revert works without a project root
+ *      (Fork 4 — designed explicitly).
+ *   2. In project mode, the project sibling
+ *      `<projectRoot>/.primitive/sync-backups/<env>/<appId>/`.
+ *   3. Otherwise (bare `./config` legacy default), `./config-snapshots`.
+ */
+export declare function resolveSnapshotsRoot(options: ResolveSyncDirOptions): string;
+export declare function assertSafePathComponent(value: string, label: string): void;
+/**
+ * Returns true if the path we'd use for sync data is the auto-resolved
+ * project-mode path (vs. a user-supplied --dir).
+ */
+export declare function isAutoResolvedSyncDir(userDir: string | undefined): boolean;
+/**
+ * Ensures the sync directory exists, creating it (and parents) if
+ * necessary. Returns the path.
+ */
+export declare function ensureSyncDir(options: ResolveSyncDirOptions): string;
+/**
+ * Checks whether an old-style sync state file exists at `./config/.primitive-sync.json`
+ * (the pre-project-config default path). Returns a warning message if found and
+ * the current operation is using a different (project-mode) path, or null otherwise.
+ *
+ * Callers can display this once at the start of sync commands so users know
+ * their old sync data won't be picked up automatically.
+ */
+export declare function checkLegacySyncMigration(currentSyncDir: string): string | null;

package/dist/src/lib/sync-paths.js

@@ -41,7 +41,35 @@ export function resolveSyncDir(options) {
     }
     return "./config";
 }
-function assertSafePathComponent(value, label) {
+/**
+ * Returns the snapshot-backups root for the slot a given sync operation
+ * belongs to (issue #578, Phase 1). Snapshots reuse the SAME resolution chain
+ * as `resolveSyncDir` (the resolved `ResolvedEnvironment` + `safeEnv()`), so
+ * the backup tree can never drift from the live sync tree — there is no
+ * parallel `{projectRoot, env, appId}` mini-model.
+ *
+ * Resolution order mirrors `resolveSyncDir`:
+ *   1. If userDir (legacy `--dir`) is set, snapshots live in a sibling
+ *      `<userDir>/.snapshots/` so revert works without a project root
+ *      (Fork 4 — designed explicitly).
+ *   2. In project mode, the project sibling
+ *      `<projectRoot>/.primitive/sync-backups/<env>/<appId>/`.
+ *   3. Otherwise (bare `./config` legacy default), `./config-snapshots`.
+ */
+export function resolveSnapshotsRoot(options) {
+    if (options.userDir) {
+        return join(options.userDir, ".snapshots");
+    }
+    const env = safeEnv();
+    if (env) {
+        // Same defence-in-depth as resolveSyncDir: never trust appId blindly when
+        // building a file-system path.
+        assertSafePathComponent(options.appId, "appId");
+        return join(env.projectRoot, ".primitive", "sync-backups", env.name, options.appId);
+    }
+    return "./config-snapshots";
+}
+export function assertSafePathComponent(value, label) {
     if (typeof value !== "string" ||
         value.length === 0 ||
         /[\\/]/.test(value) ||

package/dist/src/lib/sync-paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"sync-paths.js","sourceRoot":"","sources":["../../../src/lib/sync-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAY1D;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,OAA8B;IAC3D,IAAI,OAAO,CAAC,OAAO;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC;IAE5C,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;IACtB,IAAI,GAAG,EAAE,CAAC;QACR,wEAAwE;QACxE,yEAAyE;QACzE,kEAAkE;QAClE,oDAAoD;QACpD,uBAAuB,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAChD,OAAO,IAAI,CACT,GAAG,CAAC,WAAW,EACf,YAAY,EACZ,MAAM,EACN,GAAG,CAAC,IAAI,EACR,OAAO,CAAC,KAAK,CACd,CAAC;IACJ,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAS,uBAAuB,CAAC,KAAa,EAAE,KAAa;IAC3D,IACE,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,CAAC,MAAM,KAAK,CAAC;QAClB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;QACnB,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;QACpB,KAAK,KAAK,GAAG;QACb,KAAK,KAAK,EAAE,EACZ,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,WAAW,KAAK,mBAAmB,KAAK,EAAE,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAA2B;IAC/D,IAAI,OAAO;QAAE,OAAO,KAAK,CAAC;IAC1B,OAAO,OAAO,EAAE,KAAK,IAAI,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAA8B;IAC1D,MAAM,GAAG,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,OAAO;IACd,IAAI,CAAC;QACH,OAAO,qBAAqB,EAAE,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CAAC,cAAsB;IAC7D,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,sBAAsB,CAAC,CAAC;IAC/D,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,sEAAsE;IACtE,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACtC,IAAI,cAAc,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC9C,OAAO,CACL,4DAA4D;QAC5D,0BAA0B,cAAc,IAAI;QAC5C,6DAA6D,CAC9D,CAAC;AACJ,CAAC"}
+{"version":3,"file":"sync-paths.js","sourceRoot":"","sources":["../../../src/lib/sync-paths.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,93 @@
+declare const IOS_TEMPLATE_URL = "https://api.github.com/repos/Primitive-Labs/primitive-ios-template/tarball/main";
+export interface DownloadTemplateOptions {
+    targetDir: string;
+    templateUrl?: string;
+    onProgress?: (status: string) => void;
+}
+/**
+ * Check if a directory is empty.
+ */
+export declare function isDirectoryEmpty(dir: string): boolean;
+/**
+ * Downloads and extracts the Primitive app template.
+ * The tarball extracts to a subfolder, so we strip that prefix by moving contents up.
+ */
+export declare function downloadAndExtractTemplate(options: DownloadTemplateOptions): Promise<void>;
+export interface UpdateEnvResult {
+    envUpdated: boolean;
+    envProductionUpdated: boolean;
+}
+/**
+ * Updates .env and .env.production files with the app ID and server URLs.
+ * For .env, if it doesn't exist but .env.example does, copies from example first.
+ * Returns information about which files were updated.
+ */
+export declare function updateEnvFile(targetDir: string, appId: string, serverUrl: string, appName?: string): UpdateEnvResult;
+/**
+ * Runs pnpm install in the target directory.
+ * Uses npx to ensure corepack/packageManager compatibility.
+ */
+export declare function runPnpmInstall(targetDir: string): Promise<void>;
+/**
+ * Checks if pnpm is installed globally.
+ */
+export declare function isPnpmInstalled(): Promise<boolean>;
+/**
+ * Installs pnpm globally using npm.
+ */
+export declare function installPnpmGlobally(): Promise<void>;
+/**
+ * Checks if the primitive CLI is installed and available in PATH.
+ * Checks for the `primitive` command directly, which covers installs via
+ * npm, pnpm, yarn, or any other package manager.
+ */
+export declare function isPrimitiveCliInstalled(): Promise<boolean>;
+export declare function gitInitRepo(targetDir: string): Promise<void>;
+export declare function gitInitialCommit(targetDir: string): Promise<void>;
+/**
+ * Checks whether a TCP port is currently in use on localhost.
+ * Tries both IPv4 (127.0.0.1) and IPv6 (::1) since a server may only
+ * bind to one address family.
+ */
+export declare function isPortFree(port: number): Promise<boolean>;
+/**
+ * Pins the dev server port in vite.config.{ts,js,mts,mjs} by injecting or
+ * updating the `server.port` field. Returns true if a config file was found
+ * and patched.
+ */
+export declare function updateViteConfig(targetDir: string, port: number): boolean;
+/**
+ * Updates port-sensitive env vars (VITE_OAUTH_REDIRECT_URI, VITE_BASE_URL)
+ * in the project's .env file to point at the given localhost port.
+ */
+export declare function updateEnvPort(targetDir: string, port: number): void;
+/**
+ * Starting from `startPort` (default 5173), finds the first free port and
+ * returns which ports were already occupied and which port vite will bind to.
+ * `exhausted` is true when all checked ports were occupied and the returned
+ * port is a best-guess beyond the checked range.
+ */
+export declare function findDevPort(startPort?: number, maxChecks?: number): Promise<{
+    availablePort: number;
+    takenPorts: number[];
+    exhausted: boolean;
+}>;
+export { IOS_TEMPLATE_URL };
+/**
+ * Updates primitive.json in the iOS template with app ID, server URL, and app name.
+ * Replaces __PRIMITIVE_*__ placeholder values.
+ * Returns true if the file was found and updated.
+ */
+export declare function updatePrimitiveJson(targetDir: string, appId: string, serverUrl: string, appName?: string): boolean;
+/**
+ * Checks if Xcode command-line tools are installed.
+ */
+export declare function isXcodeInstalled(): Promise<boolean>;
+/**
+ * Runs `swift package resolve` in the target directory to download SPM dependencies.
+ */
+export declare function runSwiftPackageResolve(targetDir: string): Promise<void>;
+/**
+ * Installs the primitive CLI (primitive-admin) globally using npm.
+ */
+export declare function installPrimitiveCli(): Promise<void>;

package/dist/src/lib/token-inject.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Pure helpers for the `primitive tokens inject` command (issue #420).
+ *
+ * Kept separate from the commander wrapper in `commands/tokens.ts` so the
+ * snippet building, shared-secret generation, and one-shot localhost server
+ * can be unit-tested without a live backend or a spawned CLI process.
+ */
+/** Default TTL for injected tokens — short-lived per the #420 design (30 minutes). */
+export declare const DEFAULT_INJECT_TTL = "30m";
+/** Output modes for `--print`. `snippet` is the default (Fork 5). */
+export type PrintMode = "snippet" | "env" | "token";
+/**
+ * Build the browser console one-liner that applies a token via the
+ * `window.__PRIMITIVE_SET_TOKEN__` hook installed by `<DevTools>`.
+ */
+export declare function buildSnippet(token: string): string;
+/** Render the output for a given `--print` mode. */
+export declare function buildPrintOutput(mode: PrintMode, token: string): string;
+/** Generate a random, URL-safe shared secret for the `--serve` endpoint. */
+export declare function generateSharedSecret(): string;
+/**
+ * Copy text to the system clipboard using whatever native tool is available.
+ * No new npm dependency — shells out to `pbcopy` (macOS), `xclip`/`xsel`
+ * (Linux), or `clip` (Windows). Returns `true` on success, `false` if no
+ * clipboard tool is available or the copy failed (caller degrades gracefully).
+ */
+export declare function copyToClipboard(text: string): boolean;
+export interface ServeTokenHandle {
+    /** Full URL (incl. shared-secret query param) the consumer should fetch. */
+    url: string;
+    /** The random shared secret embedded in `url`. */
+    secret: string;
+    /** Port the server bound to (>30000). */
+    port: number;
+    /** Resolves once the token has been served once (server then closes). */
+    done: Promise<void>;
+    /** Manually shut the server down (e.g. on Ctrl-C or test cleanup). */
+    stop: () => void;
+}
+/**
+ * Boot a one-shot HTTP server bound to `127.0.0.1` that serves `token` exactly
+ * once, then shuts down. Security model:
+ *   - binds loopback only (never 0.0.0.0)
+ *   - requires a random shared-secret `?key=` query param; requests without the
+ *     correct secret get 403 and do NOT consume the one-shot read
+ *   - returns CORS headers so the documented cross-origin browser `fetch` can
+ *     actually read the response; a CORS preflight (`OPTIONS`) is answered 204
+ *     WITHOUT consuming the one-shot read or shutting the server down
+ *   - the one-shot consumption + shutdown happen ONLY on the authorized `GET`
+ *     that actually delivers the token (correct secret) — never on a preflight,
+ *     a secret-rejected request, or a wrong path
+ *   - retries random ports >30000 on collision (>= 5 attempts)
+ */
+export declare function serveTokenOnce(token: string, opts?: {
+    path?: string;
+}): Promise<ServeTokenHandle>;