@tenderprompt/accounts 0.6.1 → 0.8.0

package/dist/main.js

@@ -1,8 +1,8 @@
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
-import { copyFile, mkdir, readFile } from "node:fs/promises";
-import { basename, dirname, relative, resolve, sep } from "node:path";
-import { homedir, hostname } from "node:os";
+import { copyFile, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rm } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { homedir, hostname, tmpdir } from "node:os";
 import { AgentApiClient } from "./api.js";
 import { CLI_AUTH_SCHEMA, DEFAULT_AUTH_PROFILE, createDefaultAuthStore, validateAuthProfile, validateNamedAuthProfile, } from "./auth-store.js";
 import { labelLocalArtifact, verifyArtifact } from "./artifact.js";
@@ -130,8 +130,24 @@ async function execute(topic, options, cwd, runtime) {
             return { value: await preview(cwd, options, runtime) };
         case "source status":
             return { value: await sourceStatus(cwd, options, runtime) };
+        case "source branches":
+            return { value: await sourceBranches(cwd, options, runtime) };
+        case "source log":
+            return { value: await sourceLog(cwd, options, runtime) };
+        case "source compare":
+            return { value: await sourceCompare(cwd, options, runtime) };
+        case "source default set":
+            return { value: await sourceDefaultSet(cwd, options, runtime) };
+        case "source promote":
+            return { value: await sourcePromote(cwd, options, runtime) };
+        case "source history replace":
+            return { value: await sourceHistoryReplace(cwd, options, runtime) };
+        case "source operation status":
+            return { value: await sourceOperationStatus(cwd, options, runtime) };
         case "source connect":
             return { value: await sourceConnect(cwd, options, runtime) };
+        case "source pull":
+            return { value: await sourcePull(cwd, options, runtime) };
         case "source token":
             return { value: await sourceToken(cwd, options, runtime) };
         case "source push":
@@ -150,11 +166,8 @@ async function execute(topic, options, cwd, runtime) {
     }
 }
 async function sourceStatus(cwd, options, runtime) {
-    const context = await loadProjectContext(cwd);
-    if (!context.link)
-        throw new CliError("project_not_linked", "This app is not linked to a Tender Accounts project.", "tender-accounts link --json");
-    const projectId = requiredProjectId(context.link.projectId);
-    const { client } = await authenticatedClient(cwd, context.link, options, runtime);
+    const context = await optionalContext(cwd);
+    const { client, projectId } = await sourceProjectAccess(cwd, context?.link ?? null, options, runtime, false);
     const result = await client.sourceRepository(projectId);
     return {
         status: result.repository ? "connected" : "not_connected",
@@ -162,6 +175,517 @@ async function sourceStatus(cwd, options, runtime) {
         repository: result.repository,
     };
 }
+async function sourceBranches(cwd, options, runtime) {
+    const access = await sourceReadAccess(cwd, options, runtime);
+    let credential = null;
+    try {
+        const token = await access.client.sourceToken(access.repository.id, 15 * 60, "read");
+        credential = token.token;
+        const result = await runtime.captureCommand("git", ["ls-remote", "--heads", access.repository.remoteUrl], cwd, managedGitEnvironment(runtime.environment, credential, managedGitCredentialHeaderKey(access.repository.remoteUrl)));
+        const branches = parseManagedSourceRefs(result.stdout).map(({ ref, sha }) => ({
+            name: ref.slice("refs/heads/".length),
+            sha,
+            default: ref === `refs/heads/${access.repository.defaultBranch}`,
+            providerDefault: access.repository.providerDefaultBranch !== null
+                && ref === `refs/heads/${access.repository.providerDefaultBranch}`,
+        }));
+        return {
+            status: "ready",
+            projectId: access.projectId,
+            repositoryId: access.repository.id,
+            defaultBranch: access.repository.defaultBranch,
+            providerDefaultBranch: access.repository.providerDefaultBranch,
+            branches,
+            credentialPersisted: false,
+        };
+    }
+    finally {
+        credential = null;
+    }
+}
+async function sourceLog(cwd, options, runtime) {
+    const access = await sourceReadAccess(cwd, options, runtime);
+    const branch = options.flags.get("branch") ?? access.repository.defaultBranch;
+    assertGitBranchName(branch);
+    const limit = numberFlag(options, "limit", 1, 100, 20);
+    return withManagedSourceMirror(cwd, access.repository, access.client, runtime, async (mirror) => {
+        const refs = await managedSourceMirrorRefs(mirror, runtime);
+        if (!refs.has(`refs/heads/${branch}`)) {
+            throw new CliError("source_branch_missing", `Managed source branch ${branch} does not exist.`);
+        }
+        await runtime.captureCommand("git", ["fetch", "--no-tags", "origin", `refs/heads/${branch}:refs/remotes/origin/${branch}`], mirror.path, mirror.environment);
+        const result = await runtime.captureCommand("git", ["log", `--max-count=${limit}`, "--format=%H%x09%P%x09%aI%x09%an%x09%s", `refs/remotes/origin/${branch}`], mirror.path, managedGitCheckoutEnvironment(runtime.environment));
+        return {
+            status: "ready",
+            projectId: access.projectId,
+            repositoryId: access.repository.id,
+            branch,
+            commits: result.stdout.split(/\r?\n/u).filter(Boolean).map(parseManagedSourceCommit),
+            credentialPersisted: false,
+        };
+    });
+}
+async function sourceCompare(cwd, options, runtime) {
+    const access = await sourceReadAccess(cwd, options, runtime);
+    const base = requiredFlag(options, "base");
+    const head = requiredFlag(options, "head");
+    assertGitBranchName(base);
+    assertGitBranchName(head);
+    return withManagedSourceMirror(cwd, access.repository, access.client, runtime, async (mirror) => {
+        const refs = await managedSourceMirrorRefs(mirror, runtime);
+        const missing = [base, head].filter((branch) => !refs.has(`refs/heads/${branch}`));
+        if (missing.length > 0) {
+            throw new CliError("source_branch_missing", `Managed source branch ${missing.join(", ")} does not exist.`);
+        }
+        await runtime.captureCommand("git", [
+            "fetch", "--no-tags", "origin",
+            `refs/heads/${base}:refs/remotes/origin/${base}`,
+            `refs/heads/${head}:refs/remotes/origin/${head}`,
+        ], mirror.path, mirror.environment);
+        const checkoutEnv = managedGitCheckoutEnvironment(runtime.environment);
+        const baseSha = (await runtime.captureCommand("git", ["rev-parse", `refs/remotes/origin/${base}`], mirror.path, checkoutEnv)).stdout;
+        const headSha = (await runtime.captureCommand("git", ["rev-parse", `refs/remotes/origin/${head}`], mirror.path, checkoutEnv)).stdout;
+        let mergeBase = null;
+        try {
+            mergeBase = (await runtime.captureCommand("git", ["merge-base", baseSha, headSha], mirror.path, checkoutEnv)).stdout || null;
+        }
+        catch {
+            mergeBase = null;
+        }
+        const counts = (await runtime.captureCommand("git", ["rev-list", "--left-right", "--count", `${baseSha}...${headSha}`], mirror.path, checkoutEnv)).stdout.split(/\s+/u).map(Number);
+        const changedFiles = (await runtime.captureCommand("git", ["diff", "--name-status", "--no-renames", baseSha, headSha], mirror.path, checkoutEnv)).stdout.split(/\r?\n/u).filter(Boolean);
+        const files = changedFiles.slice(0, 500).map((line) => {
+            const [status, ...path] = line.split("\t");
+            return { status, path: path.join("\t") };
+        });
+        const relationship = baseSha === headSha
+            ? "identical"
+            : mergeBase === baseSha
+                ? "fast_forward"
+                : mergeBase === headSha
+                    ? "behind"
+                    : mergeBase === null
+                        ? "unrelated"
+                        : "diverged";
+        return {
+            status: "ready",
+            projectId: access.projectId,
+            repositoryId: access.repository.id,
+            base: { branch: base, sha: baseSha, commitsOnlyHere: counts[0] ?? 0 },
+            head: { branch: head, sha: headSha, commitsOnlyHere: counts[1] ?? 0 },
+            mergeBase,
+            relationship,
+            files,
+            filesTruncated: changedFiles.length > files.length,
+            credentialPersisted: false,
+        };
+    });
+}
+async function sourceDefaultSet(cwd, options, runtime) {
+    const targetBranch = requiredFlag(options, "branch");
+    const expectedDefaultBranch = requiredFlag(options, "expected-current");
+    assertGitBranchName(targetBranch);
+    assertGitBranchName(expectedDefaultBranch);
+    return requestAndWaitForSourceOperation(cwd, options, runtime, {
+        kind: "set_default",
+        targetBranch,
+        expectedDefaultBranch,
+    });
+}
+async function sourcePromote(cwd, options, runtime) {
+    const headBranch = requiredFlag(options, "head");
+    const expectedCurrentSha = requiredSourceSha(options, "expected-current");
+    assertGitBranchName(headBranch);
+    const access = await sourceReadAccess(cwd, options, runtime);
+    const targetBranch = options.flags.get("base") ?? access.repository.defaultBranch;
+    assertGitBranchName(targetBranch);
+    return requestAndWaitForSourceOperation(cwd, options, runtime, {
+        kind: "promote",
+        targetBranch,
+        headBranch,
+        expectedCurrentSha,
+    }, access);
+}
+async function sourceHistoryReplace(cwd, options, runtime) {
+    const access = await sourceReadAccess(cwd, options, runtime);
+    const confirmation = requiredFlag(options, "confirm");
+    if (confirmation !== access.repository.id) {
+        throw new CliError("source_history_confirmation_required", "History replacement requires --confirm with the exact managed repository ID.", `tender-accounts source history replace --head ${requiredFlag(options, "head")} --expected-current <sha> --confirm ${access.repository.id} --dry-run --json`);
+    }
+    const headBranch = requiredFlag(options, "head");
+    const targetBranch = options.flags.get("target") ?? access.repository.defaultBranch;
+    const expectedCurrentSha = requiredSourceSha(options, "expected-current");
+    assertGitBranchName(headBranch);
+    assertGitBranchName(targetBranch);
+    return requestAndWaitForSourceOperation(cwd, options, runtime, {
+        kind: "history_replace",
+        targetBranch,
+        headBranch,
+        expectedCurrentSha,
+    }, access);
+}
+async function sourceOperationStatus(cwd, options, runtime) {
+    const context = await optionalContext(cwd);
+    const { client } = await authenticatedClient(cwd, context?.link ?? null, options, runtime);
+    return (await client.sourceOperation(requiredSourceOperationId(requiredFlag(options, "operation")))).operation;
+}
+async function requestAndWaitForSourceOperation(cwd, options, runtime, input, resolvedAccess) {
+    const access = resolvedAccess ?? await sourceReadAccess(cwd, options, runtime);
+    const idempotencyKey = options.flags.get("idempotency-key")
+        ?? `cli-${input.kind}-${crypto.randomUUID()}`;
+    const requested = await access.client.createSourceOperation(access.repository.id, {
+        ...input,
+        idempotencyKey,
+        dryRun: options.booleans.has("dry-run"),
+    });
+    if (options.booleans.has("no-wait"))
+        return requested.operation;
+    const timeoutSeconds = numberFlag(options, "timeout-seconds", 10, 15 * 60, 10 * 60);
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    let operation = requested.operation;
+    while (operation.status === "requested" || operation.status === "running") {
+        if (Date.now() >= deadline) {
+            throw new CliError("source_operation_timeout", `Source operation ${operation.id} is still ${operation.status}.`, `tender-accounts source operation status --operation ${operation.id} --json`);
+        }
+        await runtime.sleep(2_000);
+        operation = (await access.client.sourceOperation(operation.id)).operation;
+    }
+    if (operation.status === "failed") {
+        throw new CliError(operation.error?.code ?? "source_operation_failed", operation.error?.message ?? "The managed source operation failed.", `tender-accounts source operation status --operation ${operation.id} --json`);
+    }
+    return operation;
+}
+async function sourceReadAccess(cwd, options, runtime) {
+    const context = await optionalContext(cwd);
+    const access = await sourceProjectAccess(cwd, context?.link ?? null, options, runtime, false);
+    const source = await access.client.sourceRepository(access.projectId);
+    if (!source.repository) {
+        throw new CliError("source_repository_missing", "This project does not have a Tender-managed Git repository.");
+    }
+    if (source.repository.status !== "active") {
+        throw new CliError("source_repository_paused", "This Tender-managed repository is paused.");
+    }
+    return { ...access, repository: source.repository };
+}
+async function withManagedSourceMirror(cwd, repository, client, runtime, callback) {
+    const mirrorPath = await mkdtemp(join(tmpdir(), "tender-accounts-source-read-"));
+    let credential = null;
+    try {
+        await runtime.captureCommand("git", ["init", "--bare", mirrorPath], cwd, managedGitCheckoutEnvironment(runtime.environment));
+        await runtime.captureCommand("git", ["remote", "add", "origin", repository.remoteUrl], mirrorPath, managedGitCheckoutEnvironment(runtime.environment));
+        const token = await client.sourceToken(repository.id, 15 * 60, "read");
+        credential = token.token;
+        return await callback({
+            path: mirrorPath,
+            environment: managedGitEnvironment(runtime.environment, credential, managedGitCredentialHeaderKey(repository.remoteUrl)),
+        });
+    }
+    finally {
+        credential = null;
+        await rm(mirrorPath, { recursive: true, force: true });
+    }
+}
+function parseManagedSourceRefs(stdout) {
+    const refs = [];
+    for (const line of stdout.split(/\r?\n/u)) {
+        const match = /^([0-9a-f]{40})\s+(refs\/heads\/[A-Za-z0-9._/-]{1,480})$/u.exec(line);
+        if (match?.[1] && match[2])
+            refs.push({ sha: match[1], ref: match[2] });
+    }
+    return refs.sort((left, right) => left.ref.localeCompare(right.ref));
+}
+async function managedSourceMirrorRefs(mirror, runtime) {
+    const result = await runtime.captureCommand("git", ["ls-remote", "--heads", "origin"], mirror.path, mirror.environment);
+    return new Map(parseManagedSourceRefs(result.stdout).map(({ ref, sha }) => [ref, sha]));
+}
+function parseManagedSourceCommit(line) {
+    const [sha, parents, authoredAt, author, ...subject] = line.split("\t");
+    return {
+        sha,
+        parents: parents ? parents.split(" ").filter(Boolean) : [],
+        authoredAt,
+        author,
+        subject: subject.join("\t"),
+    };
+}
+function requiredSourceSha(options, name) {
+    const value = requiredFlag(options, name);
+    if (!/^[0-9a-f]{40}$/u.test(value)) {
+        throw new CliError("source_revision_invalid", `--${name} must be an exact lowercase 40-character Git SHA.`);
+    }
+    return value;
+}
+function requiredSourceOperationId(value) {
+    if (!/^sop_[A-Za-z0-9_-]{8,64}$/u.test(value)) {
+        throw new CliError("source_operation_id_invalid", "--operation must be the sop_ ID returned by a source mutation.");
+    }
+    return value;
+}
+async function sourcePull(cwd, options, runtime) {
+    const context = await optionalContext(cwd);
+    const access = await sourceProjectAccess(cwd, context?.link ?? null, options, runtime, true);
+    const source = await access.client.sourceRepository(access.projectId);
+    if (!source.repository) {
+        throw new CliError("source_repository_missing", "This project does not have an active Tender-managed Git repository to pull.", "Open the merchant-hosted connected repository, or ask a merchant administrator to connect Tender-managed Git.");
+    }
+    const repository = source.repository;
+    if (repository.status !== "active") {
+        throw new CliError("source_repository_paused", "This Tender-managed repository is paused and cannot be pulled.", "Use tender-accounts source status --project <project-id> --json to inspect the authoritative source.");
+    }
+    const credentialHeaderKey = managedGitCredentialHeaderKey(repository.remoteUrl);
+    const remote = options.flags.get("remote") ?? "tender";
+    assertGitRemoteName(remote);
+    const existingGitRoot = await optionalGitRoot(cwd, runtime);
+    let checkoutRoot;
+    let action;
+    let selectedRemote = remote;
+    let selectedBranch = repository.defaultBranch;
+    let beforeRevision = null;
+    if (!existingGitRoot) {
+        const entries = await readdir(cwd);
+        if (entries.length > 0) {
+            throw new CliError("source_pull_target_not_empty", "Tender can clone the connected repository only into an empty directory.", "Run this command from an empty workspace, or open the existing matching Git checkout and retry there.");
+        }
+        checkoutRoot = cwd;
+        action = "clone";
+    }
+    else {
+        checkoutRoot = existingGitRoot;
+        action = "pull";
+        selectedRemote = await matchingSourceRemote(checkoutRoot, remote, repository.remoteUrl, runtime);
+        selectedBranch = (await runtime.captureCommand("git", ["branch", "--show-current"], checkoutRoot)).stdout;
+        if (!selectedBranch) {
+            throw new CliError("source_pull_detached_head", "Tender will not pull while the checkout has a detached HEAD.", `Switch to ${repository.defaultBranch}, then retry tender-accounts source pull.`);
+        }
+        const state = await sourceState(checkoutRoot, runtime);
+        if (state.dirty) {
+            throw new CliError("source_pull_dirty_worktree", "Tender will not pull over uncommitted or untracked files.", "Commit, stash, or remove the local changes, then retry tender-accounts source pull.");
+        }
+        beforeRevision = state.revision;
+    }
+    assertGitBranchName(selectedBranch);
+    let appRoot = managedSourceAppRoot(checkoutRoot, repository.workingDirectory);
+    if (action === "pull") {
+        appRoot = await verifiedManagedSourceAppRoot(checkoutRoot, repository.workingDirectory);
+        await compatibleManagedSourceContext(appRoot, access.projectId, access.apiUrl);
+    }
+    if (options.booleans.has("dry-run")) {
+        return {
+            status: "planned",
+            action,
+            projectId: access.projectId,
+            repositoryId: repository.id,
+            remote: selectedRemote,
+            remoteUrl: repository.remoteUrl,
+            branch: selectedBranch,
+            checkoutRoot,
+            appRoot,
+            credentialIssued: false,
+            wroteFiles: false,
+        };
+    }
+    let credential = null;
+    try {
+        const token = await access.client.sourceToken(repository.id, 15 * 60);
+        if (token.remoteUrl !== repository.remoteUrl) {
+            throw new CliError("source_token_target_mismatch", "Tender refused a repository credential whose target did not match the connected source.");
+        }
+        credential = token.token;
+        const environment = managedGitEnvironment(runtime.environment, credential, credentialHeaderKey);
+        if (action === "clone") {
+            await runtime.captureCommand("git", [
+                "clone",
+                "--no-checkout",
+                "--no-recurse-submodules",
+                "--origin", selectedRemote,
+                "--branch", repository.defaultBranch,
+                repository.remoteUrl,
+                ".",
+            ], checkoutRoot, environment);
+        }
+        else {
+            await runtime.captureCommand("git", ["fetch", "--no-recurse-submodules", selectedRemote, selectedBranch], checkoutRoot, environment);
+        }
+    }
+    finally {
+        credential = null;
+    }
+    const checkoutEnvironment = managedGitCheckoutEnvironment(runtime.environment);
+    if (action === "clone") {
+        await runtime.captureCommand("git", ["reset", "--hard", "HEAD"], checkoutRoot, checkoutEnvironment);
+    }
+    else {
+        await runtime.captureCommand("git", ["merge", "--ff-only", "FETCH_HEAD"], checkoutRoot, checkoutEnvironment);
+    }
+    appRoot = await verifiedManagedSourceAppRoot(checkoutRoot, repository.workingDirectory);
+    const pulledContext = await compatibleManagedSourceContext(appRoot, access.projectId, access.apiUrl);
+    const linkCreated = !pulledContext.link;
+    const linkPath = linkCreated
+        ? await writeProjectLink(appRoot, {
+            schema: CLI_LINK_SCHEMA,
+            projectId: access.projectId,
+            apiUrl: access.apiUrl,
+        })
+        : pulledContext.linkPath;
+    const afterRevision = (await sourceState(checkoutRoot, runtime)).revision;
+    return {
+        status: action === "clone" ? "cloned" : beforeRevision === afterRevision ? "up_to_date" : "updated",
+        action,
+        projectId: access.projectId,
+        repositoryId: repository.id,
+        remote: selectedRemote,
+        branch: selectedBranch,
+        checkoutRoot,
+        appRoot,
+        sourceRevision: afterRevision,
+        linkPath,
+        linkCreated,
+        credentialPersisted: false,
+        next: appRoot === checkoutRoot
+            ? "tender-accounts doctor --json"
+            : `tender-accounts doctor --cwd ${repository.workingDirectory} --json`,
+    };
+}
+async function compatibleManagedSourceContext(appRoot, projectId, apiUrl) {
+    const context = await loadProjectContext(appRoot).catch((error) => {
+        if (error instanceof CliError && error.code === "file_missing") {
+            throw new CliError("source_checkout_config_missing", `The connected repository does not contain tender-accounts.json at ${appRoot}.`, "Ask a merchant administrator to repair the managed source working directory before continuing.");
+        }
+        throw error;
+    });
+    if (context.link && (context.link.projectId !== projectId
+        || context.link.apiUrl !== apiUrl)) {
+        throw new CliError("source_checkout_link_conflict", "The pulled app is already linked to a different Tender project or API origin.", "Do not replace the link automatically; verify the checkout and project with a merchant administrator.");
+    }
+    return context;
+}
+async function sourceProjectAccess(cwd, link, options, runtime, requireDeveloper) {
+    const resolved = await authenticatedClient(cwd, link, options, runtime);
+    const principal = await resolved.client.whoami();
+    if (resolved.profile)
+        await savePrincipalSummary(runtime.authStore, resolved.profile, principal);
+    const explicitProject = options.flags.get("project");
+    const requestedProject = explicitProject ? requiredProjectId(explicitProject) : link?.projectId;
+    const project = requestedProject
+        ? principal.projects.find((candidate) => candidate.projectId === requestedProject)
+        : principal.projects.length === 1 ? principal.projects[0] : undefined;
+    if (!project) {
+        throw new CliError(requestedProject ? "project_not_permitted" : "project_required", requestedProject
+            ? "The current credential is not permitted to use that project."
+            : "The credential grants more than one project; select one explicitly.", `tender-accounts source status --project ${principal.projects[0]?.projectId ?? "prj_..."} --json`);
+    }
+    if (explicitProject && link && project.projectId !== link.projectId) {
+        throw new CliError("project_link_mismatch", "The requested project does not match this checkout's Tender link.", "Run the command from an empty workspace, or use the project already recorded in .tender/link.json.");
+    }
+    if (requireDeveloper && project.role !== "developer") {
+        throw new CliError("project_role_insufficient", "The selected project grant is read-only and cannot issue a repository credential.", "Ask a merchant administrator for developer access to this exact project.");
+    }
+    return { client: resolved.client, apiUrl: resolved.apiUrl, projectId: project.projectId };
+}
+async function optionalGitRoot(cwd, runtime) {
+    try {
+        return resolve((await runtime.captureCommand("git", ["rev-parse", "--show-toplevel"], cwd)).stdout);
+    }
+    catch {
+        return null;
+    }
+}
+async function matchingSourceRemote(gitRoot, requestedRemote, remoteUrl, runtime) {
+    const remotes = (await runtime.captureCommand("git", ["remote"], gitRoot)).stdout.split(/\r?\n/u).filter(Boolean);
+    const matches = [];
+    for (const remote of remotes) {
+        const current = (await runtime.captureCommand("git", ["remote", "get-url", remote], gitRoot)).stdout;
+        if (current === remoteUrl)
+            matches.push(remote);
+        if (remote === requestedRemote && current !== remoteUrl) {
+            throw new CliError("source_remote_conflict", `Git remote ${requestedRemote} points somewhere other than this project's connected source.`, "Open the matching checkout or choose its existing remote with --remote after verifying the URL.");
+        }
+    }
+    if (matches.includes(requestedRemote))
+        return requestedRemote;
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length > 1) {
+        throw new CliError("source_remote_ambiguous", "More than one Git remote points to the connected Tender source.", "Select the intended existing remote explicitly with --remote.");
+    }
+    throw new CliError("source_checkout_mismatch", "This Git checkout does not match the project's connected Tender source.", "Run tender-accounts source pull from an empty workspace to clone the exact repository.");
+}
+function managedSourceAppRoot(checkoutRoot, workingDirectory) {
+    if (workingDirectory === ".")
+        return checkoutRoot;
+    if (!workingDirectory || workingDirectory.startsWith("/") || workingDirectory.includes("\\") || workingDirectory.includes("%")) {
+        throw new CliError("source_working_directory_invalid", "The managed source working directory is unsafe.");
+    }
+    const segments = workingDirectory.split("/");
+    if (segments.some((segment) => !segment || segment === "." || segment === ".." || !/^[A-Za-z0-9._-]+$/u.test(segment))) {
+        throw new CliError("source_working_directory_invalid", "The managed source working directory is unsafe.");
+    }
+    const appRoot = resolve(checkoutRoot, workingDirectory);
+    const pathFromCheckout = relative(checkoutRoot, appRoot);
+    if (pathFromCheckout === ".." || pathFromCheckout.startsWith(`..${sep}`)) {
+        throw new CliError("source_working_directory_invalid", "The managed source working directory escapes the checkout.");
+    }
+    return appRoot;
+}
+async function verifiedManagedSourceAppRoot(checkoutRoot, workingDirectory) {
+    const lexicalAppRoot = managedSourceAppRoot(checkoutRoot, workingDirectory);
+    const realCheckoutRoot = await realpath(checkoutRoot);
+    let cursor = realCheckoutRoot;
+    if (workingDirectory !== ".") {
+        for (const segment of workingDirectory.split("/")) {
+            cursor = resolve(cursor, segment);
+            let entry;
+            try {
+                entry = await lstat(cursor);
+            }
+            catch (error) {
+                if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+                    throw new CliError("source_working_directory_missing", `The managed source working directory does not exist: ${workingDirectory}.`, "Ask a merchant administrator to repair the connected source working directory.");
+                }
+                throw error;
+            }
+            if (entry.isSymbolicLink() || !entry.isDirectory()) {
+                throw new CliError("source_working_directory_unsafe", `The managed source working directory contains a symlink or non-directory component: ${workingDirectory}.`, "Replace it with regular directories inside the connected repository before retrying.");
+            }
+        }
+    }
+    const realAppRoot = await realpath(lexicalAppRoot);
+    const pathFromCheckout = relative(realCheckoutRoot, realAppRoot);
+    if (pathFromCheckout === ".." || pathFromCheckout.startsWith(`..${sep}`)) {
+        throw new CliError("source_working_directory_unsafe", "The managed source working directory escapes the checkout.");
+    }
+    return lexicalAppRoot;
+}
+function managedGitCredentialHeaderKey(remoteUrl) {
+    let url;
+    try {
+        url = new URL(remoteUrl);
+    }
+    catch {
+        throw new CliError("source_remote_invalid", "The connected managed Git URL is invalid.");
+    }
+    if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) {
+        throw new CliError("source_remote_invalid", "The connected managed Git URL must be credential-free HTTPS without query parameters or fragments.");
+    }
+    return `http.${url.toString()}.extraHeader`;
+}
+function managedGitEnvironment(environment, credential, credentialHeaderKey) {
+    return {
+        ...environment,
+        GIT_CONFIG_COUNT: "1",
+        GIT_CONFIG_KEY_0: credentialHeaderKey,
+        GIT_CONFIG_VALUE_0: `Authorization: Bearer ${credential}`,
+        GIT_TERMINAL_PROMPT: "0",
+        GIT_LFS_SKIP_SMUDGE: "1",
+    };
+}
+function managedGitCheckoutEnvironment(environment) {
+    return {
+        ...environment,
+        GIT_TERMINAL_PROMPT: "0",
+        GIT_LFS_SKIP_SMUDGE: "1",
+    };
+}
 async function sourceConnect(cwd, options, runtime) {
     const context = await loadProjectContext(cwd);
     if (!context.link)
@@ -229,9 +753,7 @@ async function sourcePush(cwd, options, runtime) {
     await ensureGitRemote(gitRoot, remote, source.repository.remoteUrl, runtime);
     const currentBranch = (await runtime.captureCommand("git", ["branch", "--show-current"], gitRoot)).stdout;
     const branch = options.flags.get("branch") ?? (currentBranch || source.repository.defaultBranch);
-    if (!/^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$/u.test(branch)) {
-        throw new CliError("source_branch_invalid", "The managed source branch name is invalid.");
-    }
+    assertGitBranchName(branch);
     const state = await sourceState(gitRoot, runtime);
     let credential = null;
     try {
@@ -268,9 +790,7 @@ async function requireGitRoot(root, runtime) {
     }
 }
 async function ensureGitRemote(gitRoot, remote, remoteUrl, runtime) {
-    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u.test(remote)) {
-        throw new CliError("source_remote_invalid", "The Git remote name is invalid.");
-    }
+    assertGitRemoteName(remote);
     const remotes = (await runtime.captureCommand("git", ["remote"], gitRoot)).stdout.split(/\r?\n/u).filter(Boolean);
     if (!remotes.includes(remote)) {
         await runtime.captureCommand("git", ["remote", "add", remote, remoteUrl], gitRoot);
@@ -281,6 +801,16 @@ async function ensureGitRemote(gitRoot, remote, remoteUrl, runtime) {
         throw new CliError("source_remote_conflict", `Git remote ${remote} already points somewhere else. Tender will not replace it automatically.`, `Choose another name with --remote, or update ${remote} yourself after verifying the URL.`);
     }
 }
+function assertGitRemoteName(remote) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u.test(remote)) {
+        throw new CliError("source_remote_invalid", "The Git remote name is invalid.");
+    }
+}
+function assertGitBranchName(branch) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$/u.test(branch)) {
+        throw new CliError("source_branch_invalid", "The managed source branch name is invalid.");
+    }
+}
 function safeRepositoryName(value) {
     const normalized = value.replaceAll(/[^A-Za-z0-9._-]+/gu, "-").replace(/^-+|-+$/gu, "");
     return normalized.length >= 2 ? normalized.slice(0, 100) : "tender-app";
@@ -1076,6 +1606,15 @@ function commandTopic(argv) {
         const child = argv[1];
         if (!child || child.startsWith("--"))
             return { topic: "help", values: [parent] };
+        if (parent === "source" && (child === "default" || child === "history" || child === "operation")) {
+            const grandchild = argv[2];
+            if (!grandchild || grandchild.startsWith("--"))
+                return { topic: "help", values: [`${parent} ${child}`] };
+            if (argv.includes("--help") || argv.includes("-h")) {
+                return { topic: "help", values: [`${parent} ${child} ${grandchild}`] };
+            }
+            return { topic: `${parent} ${child} ${grandchild}`, values: argv.slice(3) };
+        }
         if (argv.includes("--help") || argv.includes("-h"))
             return { topic: "help", values: [`${parent} ${child}`] };
         return { topic: `${parent} ${child}`, values: argv.slice(2) };
@@ -1154,7 +1693,23 @@ function assertAllowedOptions(topic, options) {
             "timeout-seconds",
             "return-path",
         ],
-        "source status": [...common, ...authentication],
+        "source status": [...common, ...authentication, "project"],
+        "source branches": [...common, ...authentication, "project"],
+        "source log": [...common, ...authentication, "project", "branch", "limit"],
+        "source compare": [...common, ...authentication, "project", "base", "head"],
+        "source default set": [
+            ...common, ...authentication, "project", "branch", "expected-current",
+            "idempotency-key", "dry-run", "no-wait", "timeout-seconds",
+        ],
+        "source promote": [
+            ...common, ...authentication, "project", "head", "base", "expected-current",
+            "idempotency-key", "dry-run", "no-wait", "timeout-seconds",
+        ],
+        "source history replace": [
+            ...common, ...authentication, "project", "head", "target", "expected-current", "confirm",
+            "idempotency-key", "dry-run", "no-wait", "timeout-seconds",
+        ],
+        "source operation status": [...common, ...authentication, "operation"],
         "source connect": [
             ...common,
             ...authentication,
@@ -1166,6 +1721,7 @@ function assertAllowedOptions(topic, options) {
             "working-directory",
             "artifact-path",
         ],
+        "source pull": [...common, ...authentication, "project", "remote", "dry-run"],
         "source token": [...common, ...authentication, "ttl-seconds"],
         "source push": [...common, ...authentication, "branch", "remote"],
         tail: [
@@ -1298,9 +1854,20 @@ function helpText(topic) {
         check: "Usage: tender-accounts check [--json]\n\nRun the app's declared validation command.",
         build: "Usage: tender-accounts build [--json]\n\nRun validation and packaging, then verify the complete portable artifact.",
         preview: "Usage: tender-accounts preview [--dry-run] [--no-wait] [--timeout-seconds N] [--return-path /account] [--json]\n\nBuild and submit an exact preview. --dry-run validates locally without authentication or upload.",
-        source: "Usage: tender-accounts source <status|connect|token|push> [options]\n\nUse Tender-managed Git for the linked gateway or service project.",
-        "source status": "Usage: tender-accounts source status [--json]\n\nRead the managed repository, immutable build contract, and recent source builds for this linked project.",
+        source: "Usage: tender-accounts source <status|branches|log|compare|connect|pull|push|default|promote|history|operation> [options]\n\nUse standard Git through Tender for a gateway or service project. Source changes never publish production directly.",
+        "source status": "Usage: tender-accounts source status [--project PROJECT_ID] [--json]\n\nRead the managed repository, immutable build contract, and recent source builds. --project works before a checkout is linked.\n\nExamples:\n  tender-accounts source status --project prj_... --json\n  tender-accounts source status --json",
+        "source branches": "Usage: tender-accounts source branches [--project PROJECT_ID] [--json]\n\nList exact branch refs and identify Tender's authoritative default separately from the provider's create-time default. Uses a short-lived read credential without persisting it.",
+        "source log": "Usage: tender-accounts source log [--project PROJECT_ID] [--branch BRANCH] [--limit 20] [--json]\n\nRead bounded commit history from one exact managed branch without requiring a checkout.",
+        "source compare": "Usage: tender-accounts source compare [--project PROJECT_ID] --base BRANCH --head BRANCH [--json]\n\nCompare exact managed refs and report identical, fast-forward, behind, diverged, or unrelated history plus a bounded file list.",
+        "source default": "Usage: tender-accounts source default set --branch BRANCH --expected-current BRANCH [--dry-run] [--json]",
+        "source default set": "Usage: tender-accounts source default set [--project PROJECT_ID] --branch BRANCH --expected-current BRANCH [--idempotency-key KEY] [--dry-run] [--no-wait] [--json]\n\nSet an existing branch as Tender's authoritative default with compare-and-swap. This metadata-only operation cannot change production.",
+        "source promote": "Usage: tender-accounts source promote [--project PROJECT_ID] --head BRANCH [--base BRANCH] --expected-current SHA [--idempotency-key KEY] [--dry-run] [--no-wait] [--json]\n\nPromote a successfully previewed head into the current default branch using an exact expected-SHA lease. Normal preview/publication policy applies to the resulting push; protected gateways remain preview-only.",
+        "source history": "Usage: tender-accounts source history replace --head BRANCH --expected-current SHA --confirm REPOSITORY_ID [--dry-run] [--json]",
+        "source history replace": "Usage: tender-accounts source history replace [--project PROJECT_ID] --head BRANCH [--target BRANCH] --expected-current SHA --confirm REPOSITORY_ID [--idempotency-key KEY] [--dry-run] [--no-wait] [--json]\n\nExceptional source migration only: archive the exact previous target, then replace it with an expected-SHA compare-and-swap. Automatic production publication is always suppressed.",
+        "source operation": "Usage: tender-accounts source operation status --operation sop_... [--json]",
+        "source operation status": "Usage: tender-accounts source operation status --operation sop_... [--json]\n\nRead durable status and safe evidence for one exact source operation.",
         "source connect": "Usage: tender-accounts source connect [--repo-name NAME] [--default-branch NAME] [--publication preview-only|default-branch] [--remote NAME] [--install-command COMMAND] [--working-directory PATH] [--artifact-path PATH] [--json]\n\nCreate or reconnect this linked project to Tender-managed Git. Build and artifact commands come from tender-accounts.json. Protected gateways accept preview-only publication.",
+        "source pull": "Usage: tender-accounts source pull [--project PROJECT_ID] [--remote NAME] [--dry-run] [--json]\n\nClone the exact connected Tender-managed repository into an empty workspace, or fast-forward an existing clean matching checkout. The app is linked automatically and the short-lived Git credential is never persisted.\n\nExamples:\n  tender-accounts source pull --project prj_... --dry-run --json\n  tender-accounts source pull --project prj_... --json\n  tender-accounts source pull --json",
         "source token": "Usage: tender-accounts source token [--ttl-seconds N] [--json]\n\nIssue a short-lived, repository-scoped Git credential. It is shown once and is never stored by the CLI.",
         "source push": "Usage: tender-accounts source push [--branch NAME] [--remote NAME] [--json]\n\nPush the exact committed revision with an ephemeral credential supplied only to the Git child process. Dirty working-tree changes are excluded.",
         tail: "Usage: tender-accounts tail (--delivery dly_... | --production) [--status ok,error,canceled] [--method GET,POST] [--search TEXT] [--sampling-rate 0.25] [--json]\n\nStream sanitized logs for this exact linked project. Preview tails require a succeeded dly_ delivery. Production tails require merchant-administrator authorization. Sessions expire after 15 minutes and do not persist events.",
@@ -1316,7 +1883,7 @@ function helpText(topic) {
     };
     if (topic && topics[topic])
         return topics[topic];
-    return `Tender Accounts merchant developer CLI ${CLI_VERSION}\n\nCommands:\n  init              Create a new Shopify account starter\n  auth login        Create or refresh the default login\n  auth create       Create or re-authorize a named login\n  auth activate     Bind a named login to a directory tree\n  auth deactivate   Remove an exact directory binding\n  auth status       Validate one login or scoped credential\n  auth list         List local login profiles and bindings\n  auth delete       Revoke one named login\n  auth logout       Revoke the default or every login\n  link              Link this checkout to one permitted project\n  doctor            Check developer readiness\n  dev               Run the project-owned local dev command\n  check             Run project validation\n  build             Package and verify a portable artifact\n  preview           Build and deploy an exact preview\n  source status     Inspect Tender-managed Git and recent builds\n  source connect    Connect this linked project to managed Git\n  source token      Issue a short-lived repository credential\n  source push       Push the exact commit without persisting a token\n  tail              Stream logs for one exact linked project\n  delivery status   Read preview workflow state\n  delivery preview  Mint a fresh preview session\n  delivery retry    Retry a failed preview workflow\n  skill install     Install the Tender Accounts agent skill\n  config example    Print the project configuration contract\n\nThere is intentionally no production publish command.\nRun tender-accounts <command> --help for examples.`;
+    return `Tender Accounts merchant developer CLI ${CLI_VERSION}\n\nCommands:\n  init              Create a new Shopify account starter\n  auth login        Create or refresh the default login\n  auth create       Create or re-authorize a named login\n  auth activate     Bind a named login to a directory tree\n  auth deactivate   Remove an exact directory binding\n  auth status       Validate one login or scoped credential\n  auth list         List local login profiles and bindings\n  auth delete       Revoke one named login\n  auth logout       Revoke the default or every login\n  link              Link this checkout to one permitted project\n  doctor            Check developer readiness\n  dev               Run the project-owned local dev command\n  check             Run project validation\n  build             Package and verify a portable artifact\n  preview           Build and deploy an exact preview\n  source status     Inspect Tender-managed Git and recent builds\n  source branches   List exact managed branches and default policy\n  source compare    Compare two managed branches\n  source connect    Connect this linked project to managed Git\n  source pull       Clone or fast-forward the exact connected repository\n  source token      Issue a short-lived repository credential\n  source push       Push the exact commit without persisting a token\n  source promote    Fast-forward the default after successful preview checks\n  source history    Run guarded, archived source-history migration\n  tail              Stream logs for one exact linked project\n  delivery status   Read preview workflow state\n  delivery preview  Mint a fresh preview session\n  delivery retry    Retry a failed preview workflow\n  skill install     Install the Tender Accounts agent skill\n  config example    Print the project configuration contract\n\nThere is intentionally no production publish command.\nRun tender-accounts <command> --help for examples.`;
 }
 function normalizeError(error) {
     if (error instanceof CliApiError) {