@popoverai/dotrequirements 0.24.3 → 0.26.0

package/dist/commands/link-resolution.js

@@ -0,0 +1,141 @@
+/**
+ * Pure decision logic for `dotrequirements link`'s non-interactive mode
+ * (LINK-10/11/12). No I/O: the link command gathers state (teams, projects)
+ * and these functions decide what to do — use a project, create one, rename,
+ * or stop with a decision-needed result that carries everything an AI
+ * assistant needs to ask the user and retry with a deviation flag.
+ */
+/**
+ * LINK-12.3: any deviation flag implies non-interactive mode.
+ */
+export function isNonInteractive(flags) {
+    return Boolean(flags.yes || flags.team || flags.connect || flags.create);
+}
+export function hasCapacity(team) {
+    return team.projectLimit === -1 || team.projectCount < team.projectLimit;
+}
+/**
+ * LINK-10.1, LINK-11.0, LINK-12.0, LINK-12.4
+ */
+export function resolveTeam(teams, flags) {
+    if (flags.team) {
+        const wanted = flags.team.toLowerCase();
+        const match = teams.find((t) => t.teamId === flags.team || t.name.toLowerCase() === wanted);
+        if (match)
+            return { kind: "use", team: match };
+        return {
+            kind: "no-match",
+            flag: "team",
+            provided: flags.team,
+            alternatives: teams.map((t) => `${t.name} (${t.teamId})`),
+        };
+    }
+    if (teams.length === 1) {
+        return { kind: "use", team: teams[0] };
+    }
+    return {
+        kind: "decision",
+        decision: "team",
+        message: "You belong to multiple teams — which should this project join?",
+        options: teams.map((t) => ({
+            label: `${t.name} (${t.tierName}, ${formatCapacity(t)})`,
+            retryFlag: `--team ${t.teamId}`,
+        })),
+    };
+}
+/**
+ * LINK-10.2/10.3 (default-project rule), LINK-11.1/11.2 (decision menus),
+ * LINK-12.1/12.2/12.4 (deviation flags).
+ */
+export function resolveProject(projects, team, flags) {
+    if (flags.connect) {
+        const match = projects.find((p) => p.projectSlug === flags.connect);
+        if (match)
+            return { kind: "connect", project: match, rename: false };
+        return {
+            kind: "no-match",
+            flag: "connect",
+            provided: flags.connect,
+            alternatives: projects
+                .filter((p) => p.projectSlug)
+                .map((p) => `${p.projectName} (${p.projectSlug})`),
+        };
+    }
+    if (flags.create) {
+        if (hasCapacity(team))
+            return { kind: "create" };
+        return atCapacityDecision(projects, team);
+    }
+    if (projects.length === 0) {
+        // A decision with a single possible answer is not a decision: create.
+        if (hasCapacity(team))
+            return { kind: "create" };
+        return atCapacityDecision(projects, team);
+    }
+    if (projects.length === 1 && projects[0].isDefault) {
+        // LINK-10.2: rename the untouched default project to match this repo;
+        // LINK-10.3: if the user has put content in it, connect without renaming
+        return {
+            kind: "connect",
+            project: projects[0],
+            rename: !projects[0].hasUserContent,
+        };
+    }
+    // LINK-11.1: existing projects the user chose to create — their call
+    return {
+        kind: "decision",
+        decision: "project",
+        message: "This team already has projects — connect to one, or create a new one?",
+        options: [
+            ...projects.map((p) => ({
+                label: `${p.projectName}${p.hasUserContent ? "" : " (empty)"}`,
+                retryFlag: p.projectSlug ? `--connect ${p.projectSlug}` : undefined,
+            })),
+            ...(hasCapacity(team)
+                ? [{ label: "Create a new project", retryFlag: "--create" }]
+                : []),
+        ],
+    };
+}
+/**
+ * LINK-11.2: creating is required (or requested) but the team is at its
+ * project limit. None of the remedies is a plain link retry flag.
+ */
+function atCapacityDecision(projects, team) {
+    return {
+        kind: "decision",
+        decision: "capacity",
+        message: `Team "${team.name}" is at its ${team.tierName} project limit (${formatCapacity(team)}).`,
+        options: [
+            ...projects
+                .filter((p) => p.projectSlug)
+                .map((p) => ({
+                label: `Connect to existing project ${p.projectName}`,
+                retryFlag: `--connect ${p.projectSlug}`,
+            })),
+            { label: "Delete a project you no longer need (in the web app)" },
+            { label: "Upgrade the team for more projects" },
+        ],
+    };
+}
+function formatCapacity(team) {
+    return team.projectLimit === -1
+        ? `${team.projectCount}/unlimited projects`
+        : `${team.projectCount}/${team.projectLimit} projects`;
+}
+/**
+ * Prompt-free project naming for non-interactive mode (LINK-9.0): explicit
+ * flag, then package metadata, then directory name, then a fixed fallback —
+ * never a prompt.
+ */
+export function resolveProjectName(flags, packageName, directoryName) {
+    if (flags.name)
+        return flags.name;
+    if (packageName)
+        return packageName;
+    if (directoryName && directoryName !== "/" && directoryName !== ".") {
+        return directoryName;
+    }
+    return "my-project";
+}
+//# sourceMappingURL=link-resolution.js.map

package/dist/commands/link.d.ts

@@ -1,14 +1,24 @@
+import { type LinkFlags } from "./link-resolution.js";
+export interface LinkCommandOptions extends LinkFlags {
+}
 /**
- * Link command - connect or reconnect local project to cloud.
+ * Link command - connect or reconnect local project to cloud, creating the
+ * cloud project when needed. Link owns the "upgrade local to cloud"
+ * transition.
  *
  * Requirements:
  * - LINK-1: Requires existing .requirements/ folder
  * - LINK-2: Offers refresh when credentials exist
  * - LINK-3: Uses inline OAuth (no persistent tokens)
- * - LINK-4, LINK-5: Team and project selection
+ * - LINK-4, LINK-5: Team and project selection (including the create option)
  * - LINK-6: Saves credentials to project-settings.json
- * - LINK-7: Optionally pulls requirements
+ * - LINK-7: Optionally pulls requirements (interactive only)
  * - LINK-8: Handles network errors gracefully
+ * - LINK-9: Creates the cloud project when chosen
+ * - LINK-10/11/12: Non-interactive mode for AI-driven setup
+ * - LINK-13: Non-interactive success includes share artifacts (team-invite
+ *   URL + read-only pull command) so one "yes" puts the spec in front of
+ *   the team
  */
-export declare function linkCommand(): Promise<void>;
+export declare function linkCommand(options?: LinkCommandOptions): Promise<void>;
 //# sourceMappingURL=link.d.ts.map

package/dist/commands/link.js

@@ -1,25 +1,314 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
 import { ConvexHttpClient } from "convex/browser";
 import { getConvexUrl } from "../config.js";
+import { api } from "../convex.js";
+import { WEB_APP_URL } from "../push/index.js";
 import { brand } from "../utils/brand.js";
 import { ensureGitignore } from "../utils/gitignore.js";
 import { executeOAuthFlow } from "../utils/oauth-flow.js";
-import { getOrCreateProjectSecret, promptExpiryDays, selectProject, selectTeam, } from "../utils/project-selector.js";
+import { getOrCreateProjectSecret, promptExpiryDays, selectTeam, } from "../utils/project-selector.js";
 import { findProjectRoot, readProjectSettings, writeProjectSettings, } from "../utils/project-settings.js";
 import { promptChoice, promptConfirm } from "../utils/prompts.js";
+import { hasCapacity, isNonInteractive, resolveProject, resolveProjectName, resolveTeam, } from "./link-resolution.js";
 import { pullCommand } from "./pull.js";
 /**
- * Link command - connect or reconnect local project to cloud.
+ * Link command - connect or reconnect local project to cloud, creating the
+ * cloud project when needed. Link owns the "upgrade local to cloud"
+ * transition.
  *
  * Requirements:
  * - LINK-1: Requires existing .requirements/ folder
  * - LINK-2: Offers refresh when credentials exist
  * - LINK-3: Uses inline OAuth (no persistent tokens)
- * - LINK-4, LINK-5: Team and project selection
+ * - LINK-4, LINK-5: Team and project selection (including the create option)
  * - LINK-6: Saves credentials to project-settings.json
- * - LINK-7: Optionally pulls requirements
+ * - LINK-7: Optionally pulls requirements (interactive only)
  * - LINK-8: Handles network errors gracefully
+ * - LINK-9: Creates the cloud project when chosen
+ * - LINK-10/11/12: Non-interactive mode for AI-driven setup
+ * - LINK-13: Non-interactive success includes share artifacts (team-invite
+ *   URL + read-only pull command) so one "yes" puts the spec in front of
+ *   the team
  */
-export async function linkCommand() {
+export async function linkCommand(options = {}) {
+    if (isNonInteractive(options)) {
+        await runNonInteractiveLink(options);
+        return;
+    }
+    await runInteractiveLink(options);
+}
+const EXIT_DECISION_NEEDED = 2;
+async function runNonInteractiveLink(options) {
+    // LINK-10.5/11.3: in JSON mode the single stdout line is the result object;
+    // every informational message (including the OAuth flow's, and the browser
+    // fallback URL) goes to stderr so the output stays machine-parseable.
+    const originalLog = console.log;
+    if (options.json) {
+        console.log = (...args) => console.error(...args);
+    }
+    const finish = (outcome) => {
+        console.log = originalLog;
+        if (options.json) {
+            originalLog(JSON.stringify(outcome));
+        }
+        else if (outcome.status === "decision_needed") {
+            console.log(`\n${outcome.message}`);
+            for (const opt of outcome.options) {
+                console.log(`  - ${opt.label}${opt.retryFlag ? `  (retry with: dotrequirements link ${opt.retryFlag})` : ""}`);
+            }
+        }
+        else if (outcome.status === "error") {
+            console.error(`\n✗ ${outcome.message}`);
+        }
+        else {
+            console.log(`\n✓ Linked to project: ${outcome.projectName}${outcome.renamed ? " (renamed to match this repository)" : ""}`);
+            console.log(`  Project ID: ${outcome.projectSlug}`);
+            // LINK-13: hand over the share mechanics, one per recipient surface
+            if (outcome.inviteUrl) {
+                console.log(`  Invite a teammate (web): ${outcome.inviteUrl}`);
+            }
+            if (outcome.sharePullCommand) {
+                console.log(`  Share read-only to an IDE: ${outcome.sharePullCommand}`);
+            }
+        }
+        if (outcome.status === "decision_needed") {
+            process.exitCode = EXIT_DECISION_NEEDED;
+        }
+        else if (outcome.status === "error") {
+            process.exitCode = 1;
+        }
+    };
+    try {
+        // LINK-1: same precondition as interactive
+        const cwd = process.cwd();
+        const projectRoot = findProjectRoot(cwd);
+        if (!projectRoot || projectRoot !== cwd) {
+            finish({
+                status: "error",
+                message: 'No .requirements/ folder found. Run "dotrequirements init" to initialize a project first.',
+            });
+            return;
+        }
+        // LINK-10.6: existing credentials default to refresh-same-project
+        let refreshTargetSlug;
+        try {
+            const existing = readProjectSettings(projectRoot);
+            refreshTargetSlug = existing?.projectId;
+        }
+        catch {
+            refreshTargetSlug = undefined;
+        }
+        // LINK-3 / LINK-10.7: browser auth is the only human step
+        const oauthResult = await executeOAuthFlow();
+        const client = new ConvexHttpClient(getConvexUrl());
+        client.setAuth(oauthResult.accessToken);
+        await client.mutation(api.teams.mutations.ensureDefaultTeam, {});
+        const teams = (await client.query(api.teams.queries.listForUserWithUsage));
+        if (teams.length === 0) {
+            finish({
+                status: "error",
+                message: "You are not a member of any teams. Create one at https://app.dotrequirements.io/teams/new and retry.",
+            });
+            return;
+        }
+        // LINK-10.6: refresh path — find the already-linked project. A deviation
+        // flag (--team/--connect/--create, LINK-12) overrides the refresh default
+        // and falls through to normal resolution. Settings store the raw
+        // projectId when a project has no slug, so match either.
+        if (refreshTargetSlug &&
+            !options.connect &&
+            !options.create &&
+            !options.team) {
+            for (const team of teams) {
+                const projects = await listProjects(client, team.teamId);
+                const match = projects.find((p) => p.projectSlug === refreshTargetSlug ||
+                    p.projectId === refreshTargetSlug);
+                if (match) {
+                    const settingsPath = await connectToProject(client, projectRoot, match.projectId, refreshTargetSlug);
+                    // LINK-13.2: ensureShareToken is idempotent, so a refresh hands
+                    // back the same share command rather than minting a new token
+                    const artifacts = await mintShareArtifacts(client, team.teamId, match.projectId);
+                    finish({
+                        status: "linked",
+                        projectSlug: refreshTargetSlug,
+                        projectName: match.projectName,
+                        renamed: false,
+                        settingsPath,
+                        ...artifacts,
+                    });
+                    return;
+                }
+            }
+            finish({
+                status: "error",
+                message: `Currently-linked project "${refreshTargetSlug}" was not found in your teams. Pass --connect <slug> to link a different project.`,
+            });
+            return;
+        }
+        const teamResolution = resolveTeam(teams, options);
+        if (teamResolution.kind === "no-match") {
+            finish({
+                status: "error",
+                message: `No team matched "${teamResolution.provided}". Your teams: ${teamResolution.alternatives.join(", ")}`,
+            });
+            return;
+        }
+        if (teamResolution.kind === "decision") {
+            const { kind: _kind, ...decision } = teamResolution;
+            finish({ status: "decision_needed", ...decision });
+            return;
+        }
+        const team = teamResolution.team;
+        const projects = await listProjects(client, team.teamId);
+        const projectResolution = resolveProject(projects, team, options);
+        if (projectResolution.kind === "no-match") {
+            finish({
+                status: "error",
+                message: `No project matched "${projectResolution.provided}". Projects in ${team.name}: ${projectResolution.alternatives.join(", ") || "(none)"}`,
+            });
+            return;
+        }
+        if (projectResolution.kind === "decision") {
+            const { kind: _kind, ...decision } = projectResolution;
+            finish({ status: "decision_needed", ...decision });
+            return;
+        }
+        if (projectResolution.kind === "create") {
+            // LINK-9 via LINK-12.2 (or zero-projects default)
+            const name = resolveProjectName(options, readPackageName(cwd), path.basename(cwd));
+            const created = (await client.mutation(api.projects.mutations.create, {
+                name,
+                teamId: team.teamId,
+            }));
+            const settingsPath = await connectToProject(client, projectRoot, created.projectId, created.slug);
+            const artifacts = await mintShareArtifacts(client, team.teamId, created.projectId);
+            finish({
+                status: "linked",
+                projectSlug: created.slug,
+                projectName: name,
+                renamed: false,
+                settingsPath,
+                ...artifacts,
+            });
+            return;
+        }
+        // connect (possibly renaming the empty default project, LINK-10.2)
+        let projectName = projectResolution.project.projectName;
+        let renamed = false;
+        if (projectResolution.rename) {
+            const newName = resolveProjectName(options, readPackageName(cwd), path.basename(cwd));
+            try {
+                await client.mutation(api.projects.mutations.update, {
+                    target: {
+                        type: "project",
+                        // biome-ignore lint/suspicious/noExplicitAny: CLI workspace doesn't import convex's branded Id type; the runtime value is a plain string the server validates.
+                        id: projectResolution.project.projectId,
+                    },
+                    name: newName,
+                });
+                projectName = newName;
+                renamed = true;
+            }
+            catch {
+                // LINK-10.9: renaming is admin-gated server-side — a non-admin member
+                // (e.g. invited via init --invite) still gets connected, just without
+                // the rename
+                console.error(`Note: couldn't rename the default project to "${newName}" (team admin required) — connected without renaming.`);
+            }
+        }
+        const slug = projectResolution.project.projectSlug ??
+            projectResolution.project.projectId;
+        const settingsPath = await connectToProject(client, projectRoot, projectResolution.project.projectId, slug);
+        const artifacts = await mintShareArtifacts(client, team.teamId, projectResolution.project.projectId);
+        finish({
+            status: "linked",
+            projectSlug: projectResolution.project.projectSlug,
+            projectName,
+            renamed,
+            settingsPath,
+            ...artifacts,
+        });
+    }
+    catch (error) {
+        finish({
+            status: "error",
+            message: error instanceof Error ? error.message : String(error),
+        });
+    }
+    finally {
+        console.log = originalLog;
+    }
+}
+/**
+ * LINK-13: mint the artifacts that put the spec in front of the team — a
+ * single-use team-invite URL (web reviewers) and a read-only pull command
+ * (IDE teammates). Either mint may fail without failing the connection
+ * (LINK-13.3): createInvite is admin-gated, so non-admin members link
+ * successfully and the invite URL is simply omitted.
+ */
+async function mintShareArtifacts(client, teamId, projectId) {
+    const artifacts = {};
+    try {
+        const invite = (await client.mutation(api.teamInvites.mutations.createInvite, 
+        // biome-ignore lint/suspicious/noExplicitAny: CLI workspace doesn't import convex's branded Id type; the runtime value is a plain string the server validates.
+        { target: { type: "team", id: teamId } }));
+        artifacts.inviteUrl = `${WEB_APP_URL}/invite/${invite.token}`;
+    }
+    catch {
+        // LINK-13.3: admin-gated — omit the invite URL for non-admin members
+    }
+    try {
+        const share = (await client.mutation(api.projectSecrets.mutations.ensureShareToken, 
+        // biome-ignore lint/suspicious/noExplicitAny: CLI workspace doesn't import convex's branded Id type; the runtime value is a plain string the server validates.
+        { target: { type: "project", id: projectId } }));
+        artifacts.sharePullCommand = `npx -y @popoverai/dotrequirements pull --share ${share.token}`;
+    }
+    catch {
+        // LINK-13.3: connection already succeeded — omit rather than fail
+    }
+    return artifacts;
+}
+async function listProjects(client, teamId) {
+    const projects = (await client.query(api.projectSecrets.queries.listOwnSecretsForTeam, 
+    // biome-ignore lint/suspicious/noExplicitAny: CLI workspace doesn't import convex's branded Id type; the runtime value is a plain string the server validates.
+    { target: { type: "team", id: teamId } }));
+    return projects.map((p) => ({
+        projectId: p.projectId,
+        projectName: p.projectName,
+        projectSlug: p.projectSlug,
+        isDefault: p.isDefault ?? false,
+        // Older servers don't report content state; treat unknown as content so
+        // we never rename something we can't vouch for
+        hasUserContent: p.hasUserContent ?? true,
+    }));
+}
+/**
+ * Mint (or fetch) a secret and write credentials (LINK-6). Returns the
+ * settings file path. Non-interactive: tier-default expiry, no prompts.
+ */
+async function connectToProject(client, projectRoot, projectId, slug) {
+    const secretResult = await getOrCreateProjectSecret(client, projectId, undefined);
+    writeProjectSettings(projectRoot, {
+        projectId: slug,
+        projectSecret: secretResult.secret,
+    });
+    ensureGitignore(projectRoot);
+    return path.join(projectRoot, ".requirements", "project-settings.json");
+}
+function readPackageName(cwd) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf-8"));
+        return typeof pkg.name === "string" ? pkg.name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// ============================================================================
+// Interactive mode
+// ============================================================================
+async function runInteractiveLink(options) {
     try {
         console.log(`Linking to ${brand} cloud...\n`);
         const cwd = process.cwd();
@@ -65,19 +354,38 @@ export async function linkCommand() {
             console.log("Link cancelled.");
             return;
         }
-        // LINK-5: Select project
-        const selectedProject = await selectProject(client, selectedTeam.teamId);
-        if (!selectedProject) {
-            // selectProject already shows message about no projects
+        // LINK-5: Select project — or create one (LINK-5.1, LINK-9)
+        const selection = await selectProjectOrCreate(client, selectedTeam);
+        if (selection === null) {
+            console.log("Link cancelled.");
             return;
         }
+        let projectId;
+        let projectName;
+        let projectSlugOrId;
+        if (selection === "create") {
+            // LINK-9: create with the detected default name (-n/--name overrides)
+            const defaultName = resolveProjectName(options, readPackageName(cwd), path.basename(cwd));
+            console.log(`\nCreating project "${defaultName}"...`);
+            const created = (await client.mutation(api.projects.mutations.create, {
+                name: defaultName,
+                teamId: selectedTeam.teamId,
+            }));
+            projectId = created.projectId;
+            projectName = defaultName;
+            projectSlugOrId = created.slug;
+            console.log(`✓ Created project: ${created.slug}`);
+        }
+        else {
+            projectId = selection.projectId;
+            projectName = selection.projectName;
+            projectSlugOrId = selection.projectSlug || selection.projectId;
+        }
         // AUTHZ-3: Prompt for secret expiry (paid tier only)
         const expiryDays = await promptExpiryDays(selectedTeam.tier);
         // LINK-5.3: Get or create secret for this project
         console.log("\nGetting project credentials...");
-        const secretResult = await getOrCreateProjectSecret(client, selectedProject.projectId, expiryDays);
-        const projectId = selectedProject.projectSlug || selectedProject.projectId;
-        const secret = secretResult.secret;
+        const secretResult = await getOrCreateProjectSecret(client, projectId, expiryDays);
         if (secretResult.created) {
             console.log("✓ Created new project secret");
         }
@@ -85,18 +393,21 @@ export async function linkCommand() {
             console.log("✓ Retrieved existing project secret");
         }
         // LINK-6: Write credentials to project-settings.json
-        writeProjectSettings(projectRoot, { projectId, projectSecret: secret });
+        writeProjectSettings(projectRoot, {
+            projectId: projectSlugOrId,
+            projectSecret: secretResult.secret,
+        });
         ensureGitignore(projectRoot);
         console.log("✓ Wrote credentials to .requirements/project-settings.json");
         // LINK-7: Optionally pull requirements
         const shouldPull = await promptConfirm("Pull requirements from cloud now?", true);
         if (shouldPull) {
             console.log("\nPulling requirements...");
-            await pullCommand({ project: projectId });
+            await pullCommand({ project: projectSlugOrId });
         }
         // LINK-7.2: Success message
-        console.log(`\n✓ Successfully linked to project: ${selectedProject.projectName}`);
-        console.log(`  Project ID: ${projectId}`);
+        console.log(`\n✓ Successfully linked to project: ${projectName}`);
+        console.log(`  Project ID: ${projectSlugOrId}`);
         console.log("\nDocumentation: https://docs.dotrequirements.io/getting-started");
     }
     catch (error) {
@@ -109,6 +420,48 @@ export async function linkCommand() {
         process.exit(1);
     }
 }
+/**
+ * LINK-5: project selection including the create option (LINK-5.1) when the
+ * team has capacity. Returns the chosen project, "create", or null (cancel).
+ */
+async function selectProjectOrCreate(client, team) {
+    console.log("\nFetching projects...\n");
+    const projects = await listProjects(client, team.teamId);
+    const teamOption = {
+        teamId: team.teamId,
+        name: team.name ?? "this team",
+        tier: team.tier,
+        tierName: team.tierName ?? team.tier,
+        projectCount: team.projectCount ?? projects.length,
+        projectLimit: team.projectLimit ?? -1,
+    };
+    const canCreate = hasCapacity(teamOption);
+    if (projects.length === 0) {
+        if (!canCreate) {
+            // LINK-5.2: connect is impossible; the remedies live elsewhere
+            console.log("This team has no projects and is at its project limit.");
+            console.log("Delete a project you no longer need (in the web app) or upgrade the team, then retry.\n");
+            return null;
+        }
+        const confirmed = await promptConfirm("This team has no projects. Create a new one?", true);
+        return confirmed ? "create" : null;
+    }
+    const choices = projects.map((p) => ({
+        title: p.projectSlug
+            ? `${p.projectName} (${p.projectSlug})`
+            : p.projectName,
+        value: p.projectId,
+    }));
+    if (canCreate) {
+        choices.push({ title: "Create a new project", value: "CREATE_NEW" });
+    }
+    const selected = await promptChoice("Select a project:", choices);
+    if (!selected)
+        return null;
+    if (selected === "CREATE_NEW")
+        return "create";
+    return projects.find((p) => p.projectId === selected) ?? null;
+}
 /**
  * LINK-2: Handle existing credentials - offer refresh or connect to different project
  * Returns true if user wants to continue (either refresh or different project)

package/dist/commands/pull.js

@@ -32,9 +32,14 @@ export async function pullCommand(options) {
             console.log(`\nProject: "${projectName}"`);
         }
         catch (error) {
-            // SHARE-TOKEN-CLI-2: Handle invalid/revoked tokens gracefully
+            // SHARE-TOKEN-CLI-2: Handle invalid/revoked tokens gracefully.
+            // Production redacts ConvexError messages to "Server Error" but
+            // preserves error.data — check both, or the friendly message only
+            // ever appears against dev deployments.
+            const data = error.data;
             const errorMessage = error instanceof Error ? error.message : String(error);
-            if (errorMessage.includes("Invalid share token")) {
+            if (data?.message === "Invalid share token" ||
+                errorMessage.includes("Invalid share token")) {
                 throw new Error("Invalid share token. The token may be incorrect or has been revoked.\n" +
                     "Please request a new share token from your team.");
             }
@@ -96,11 +101,23 @@ export async function pullCommand(options) {
         const filePath = existingFilePath ??
             path.join(requirementsDir, `${sanitizeFileName(doc.title)}.requirements.md`);
         const fileName = path.basename(filePath);
+        // IMPORT-1: carry the CTS run marker forward from the existing local
+        // file — pull rebuilds frontmatter from cloud data, and silently dropping
+        // the marker would strip a committed spec's import credential before a
+        // teammate ever pushes it
+        let existingCtsRun;
+        if (existingFilePath && fs.existsSync(existingFilePath)) {
+            const match = fs
+                .readFileSync(existingFilePath, "utf-8")
+                .match(/^ctsRun: (.+)$/m);
+            existingCtsRun = match?.[1].trim();
+        }
         // Build metadata with pulledAt for conflict detection
         // SYNC-CLI-EDIT-2: pulledAt is compared with cloud updatedAt during push
         const metadata = {
             pulledAt: new Date().toISOString(),
             version: doc.version,
+            ...(existingCtsRun ? { ctsRun: existingCtsRun } : {}),
             document: {
                 id: doc.documentId,
                 title: doc.title,