@overscore/cli 0.13.15 → 0.13.17

package/dist/index.js

@@ -913,7 +913,7 @@ function formatCell(value) {
 }
 async function pull(slug) {
     if (!slug) {
-        console.error("\n  Usage: npx @overscore/cli pull <dashboard-slug> [--version N]\n");
+        console.error("\n  Usage: npx @overscore/cli pull <dashboard-slug> [--version N] [--force]\n");
         console.error("  Example:");
         console.error("    npx @overscore/cli pull my-dashboard\n");
         process.exit(1);
@@ -923,35 +923,47 @@ async function pull(slug) {
     const versionParam = versionIndex !== -1 && process.argv[versionIndex + 1]
         ? process.argv[versionIndex + 1]
         : null;
-    // Resolve API key: device token → auto-create os_ key, else prompt
+    // --force skips the "directory exists, overwrite?" confirm — needed for non-interactive
+    // re-pulls (scripted rebuilds / `workspace sync`). Source is versioned in the Hub, and the
+    // clean step below already preserves node_modules + .env, so overwriting is safe.
+    const force = process.argv.includes("--force");
+    // Resolve API key: device token → auto-create os_ key, else the saved project key, else prompt.
     let apiKey = "";
     const configPath = path.join(process.env.HOME || "", ".overscore", "config");
-    if (fs.existsSync(configPath)) {
-        const cfg = parseEnv(fs.readFileSync(configPath, "utf-8"));
-        const deviceToken = cfg.OVERSCORE_DEVICE_TOKEN;
-        if (deviceToken) {
-            try {
-                const keyRes = await fetch(`${HUB_URL}/api/projects/${slug}/api-keys`, {
-                    method: "POST",
-                    headers: {
-                        Authorization: `Bearer ${deviceToken}`,
-                        "Content-Type": "application/json",
-                    },
-                    body: JSON.stringify({ name: `${slug} pull key` }),
-                });
-                if (keyRes.status === 401 || keyRes.status === 403) {
-                    console.error("\n  Error: Device token is invalid or expired. Run 'npx @overscore/cli auth login' to re-authenticate.\n");
-                    process.exit(1);
-                }
-                if (keyRes.ok) {
-                    const keyData = (await keyRes.json());
-                    apiKey = keyData.raw_key || "";
-                }
+    const cfg = fs.existsSync(configPath)
+        ? parseEnv(fs.readFileSync(configPath, "utf-8"))
+        : {};
+    const deviceToken = cfg.OVERSCORE_DEVICE_TOKEN;
+    if (deviceToken) {
+        try {
+            const keyRes = await fetch(`${HUB_URL}/api/projects/${slug}/api-keys`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${deviceToken}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({ name: `${slug} pull key` }),
+            });
+            if (keyRes.status === 401 || keyRes.status === 403) {
+                console.error("\n  Error: Device token is invalid or expired. Run 'npx @overscore/cli auth login' to re-authenticate.\n");
+                process.exit(1);
             }
-            catch {
-                // Network error — fall through to prompt
+            if (keyRes.ok) {
+                const keyData = (await keyRes.json());
+                apiKey = keyData.raw_key || "";
             }
         }
+        catch {
+            // Network error — fall through to the saved key / prompt
+        }
+    }
+    // The mint above targets /api/projects/<slug>, but `slug` is a DASHBOARD slug — for any
+    // project whose name differs from the dashboard (i.e. any multi-dashboard project) that
+    // 404s and leaves apiKey empty. Fall back to the project API key saved by `auth login`:
+    // it authorizes every dashboard in the logged-in project, which is the common pull case
+    // (and what makes non-interactive `pull` / scripted rebuilds work).
+    if (!apiKey && cfg.OVERSCORE_API_KEY) {
+        apiKey = cfg.OVERSCORE_API_KEY;
     }
     if (!apiKey) {
         console.log("  Tip: Run 'npx @overscore/cli auth login' to authenticate once and skip this step.");
@@ -989,7 +1001,7 @@ async function pull(slug) {
     const zipBuffer = Buffer.from(await res.arrayBuffer());
     // Extract to ./<slug>/
     const targetDir = path.resolve(process.cwd(), slug);
-    if (fs.existsSync(targetDir)) {
+    if (fs.existsSync(targetDir) && !force) {
         const yes = await confirm(`Directory "${slug}" already exists. Overwrite source files?`);
         if (!yes) {
             console.log("  Cancelled.\n");
@@ -1569,6 +1581,123 @@ function syncClaudeMdImports(targetDir) {
     fs.writeFileSync(claudeMdPath, updated);
     return true;
 }
+/** Recursively copy a directory (files + subdirs), overwriting at the destination. */
+function copyDirRecursive(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        const s = path.join(src, entry.name);
+        const d = path.join(dest, entry.name);
+        if (entry.isDirectory())
+            copyDirRecursive(s, d);
+        else if (entry.isFile())
+            fs.copyFileSync(s, d);
+    }
+}
+/**
+ * Derive a cross-tool AGENTS.md from an existing .claude/CLAUDE.md. Codex,
+ * Cursor, Copilot, and Gemini read AGENTS.md but do NOT resolve Claude Code's
+ * `@import` lines, so the leading @import block becomes prose "read when
+ * relevant" pointers, a reference-guides list of .claude/rules/*.md is added,
+ * and the rest of the CLAUDE.md body is kept verbatim. Returns null if the
+ * CLAUDE.md doesn't look like an Overscore artifact.
+ */
+function deriveAgentsMdFromClaudeMd(targetDir, content) {
+    const lines = content.split("\n");
+    const headingIdx = lines.findIndex((l) => /^#\s+Overscore\s+(Dashboard|Analysis)/i.test(l));
+    if (headingIdx === -1)
+        return null;
+    // The @import lines follow the heading (blank lines allowed between); the
+    // first other non-blank line begins the body.
+    const importTargets = [];
+    let bodyStart = headingIdx + 1;
+    for (let i = headingIdx + 1; i < lines.length; i++) {
+        const t = lines[i].trim();
+        if (t === "") {
+            bodyStart = i + 1;
+            continue;
+        }
+        if (t.startsWith("@")) {
+            importTargets.push(t.slice(1));
+            bodyStart = i + 1;
+            continue;
+        }
+        bodyStart = i;
+        break;
+    }
+    const body = lines.slice(bodyStart).join("\n").replace(/^\n+/, "");
+    const memBullets = importTargets.length
+        ? importTargets.map((p) => `- **${p}** — load when relevant to your task.`).join("\n")
+        : "- (this project has no shared context files yet)";
+    // Reference guides: every .claude/rules/*.md except the per-artifact memory
+    // file (already listed above as a memory pointer).
+    const memBasenames = new Set(importTargets.map((p) => path.basename(p)));
+    const rulesDir = path.join(targetDir, ".claude", "rules");
+    let refBlock = "";
+    if (fs.existsSync(rulesDir)) {
+        const ruleFiles = fs
+            .readdirSync(rulesDir)
+            .filter((f) => f.endsWith(".md") &&
+            !memBasenames.has(f) &&
+            f !== "this-dashboard.md" &&
+            f !== "this-analysis.md")
+            .sort();
+        if (ruleFiles.length > 0) {
+            refBlock =
+                "\n## Reference guides — read the relevant one when the task calls for it\n\n" +
+                    "This project's authoring rules live in these files. Read the relevant one on demand; you don't need to read them all every session.\n\n" +
+                    ruleFiles.map((f) => `- **.claude/rules/${f}**`).join("\n") +
+                    "\n";
+        }
+    }
+    return `${lines[headingIdx]}
+
+## Project instructions and memory
+
+This project keeps its context in Markdown files. You don't need to read all of them every session; load the ones relevant to your task:
+
+${memBullets}
+${refBlock}
+${body}`;
+}
+/**
+ * Ensure the cross-tool layout (Codex / Cursor / Copilot / Gemini) exists
+ * alongside Claude Code's .claude/:
+ *   - .agents/skills/ — the cross-tool Agent Skills location, mirrored from
+ *     .claude/skills so it stays current as the Hub OTA updates skills.
+ *   - AGENTS.md — a root instruction file derived from .claude/CLAUDE.md,
+ *     created only if one doesn't already exist (never clobbers user edits).
+ * This is what retrofits an existing (Claude-only) project for Codex on the
+ * next deploy / pull / `platform update`. Returns paths newly created, for
+ * reporting. Best-effort: never throws.
+ */
+function ensureCodexLayout(targetDir) {
+    const created = [];
+    try {
+        const claudeSkills = path.join(targetDir, ".claude", "skills");
+        if (fs.existsSync(claudeSkills)) {
+            const agentsSkills = path.join(targetDir, ".agents", "skills");
+            const existed = fs.existsSync(agentsSkills);
+            // Re-mirror every sync so new/updated skills propagate; only report the
+            // first-time creation to keep steady-state syncs quiet.
+            copyDirRecursive(claudeSkills, agentsSkills);
+            if (!existed)
+                created.push(".agents/skills/");
+        }
+        const agentsMdPath = path.join(targetDir, "AGENTS.md");
+        const claudeMdPath = path.join(targetDir, ".claude", "CLAUDE.md");
+        if (!fs.existsSync(agentsMdPath) && fs.existsSync(claudeMdPath)) {
+            const agents = deriveAgentsMdFromClaudeMd(targetDir, fs.readFileSync(claudeMdPath, "utf-8"));
+            if (agents) {
+                fs.writeFileSync(agentsMdPath, agents);
+                created.push("AGENTS.md");
+            }
+        }
+    }
+    catch {
+        // Non-fatal — cross-tool layout is best-effort.
+    }
+    return created;
+}
 function platformMetaPath(targetDir) {
     return path.join(targetDir, ".claude", ".platform-meta.json");
 }
@@ -1684,8 +1813,14 @@ async function syncPlatformRules(targetDir, baseUrl, apiKey) {
         }
         writePlatformMeta(targetDir, meta);
         const claudeUpdated = syncClaudeMdImports(targetDir);
-        if (written.length > 0 || claudeUpdated) {
-            console.log(`  Platform rules synced (${written.length} file${written.length === 1 ? "" : "s"}${claudeUpdated ? " + CLAUDE.md updated" : ""}).`);
+        const codexCreated = ensureCodexLayout(targetDir);
+        if (written.length > 0 || claudeUpdated || codexCreated.length > 0) {
+            const extras = [];
+            if (claudeUpdated)
+                extras.push("CLAUDE.md updated");
+            if (codexCreated.length > 0)
+                extras.push(codexCreated.join(" + ") + " added for Codex");
+            console.log(`  Platform rules synced (${written.length} file${written.length === 1 ? "" : "s"}${extras.length ? " + " + extras.join(" + ") : ""}).`);
         }
         if (preserved.length > 0) {
             console.log(`  Preserved ${preserved.length} locally-modified file${preserved.length === 1 ? "" : "s"} (Hub updates skipped):`);
@@ -1772,11 +1907,23 @@ async function platformUpdate(checkOnly = false, force = false) {
         }
         if (claudeWouldChange)
             updated.push(".claude/CLAUDE.md (@imports would be added)");
+        // Cross-tool (Codex/Cursor/Copilot/Gemini) layout a real run would create.
+        if (!fs.existsSync(path.join(process.cwd(), "AGENTS.md")) &&
+            fs.existsSync(path.join(process.cwd(), ".claude", "CLAUDE.md"))) {
+            updated.push("AGENTS.md (would be created for Codex/cross-tool)");
+        }
+        if (fs.existsSync(path.join(process.cwd(), ".claude", "skills")) &&
+            !fs.existsSync(path.join(process.cwd(), ".agents", "skills"))) {
+            updated.push(".agents/skills/ (would be created for Codex/cross-tool)");
+        }
     }
     else {
         const claudeUpdated = syncClaudeMdImports(process.cwd());
         if (claudeUpdated)
             updated.push(".claude/CLAUDE.md (@imports updated)");
+        for (const p of ensureCodexLayout(process.cwd())) {
+            updated.push(`${p} (created for Codex/cross-tool)`);
+        }
     }
     if (updated.length === 0 && preserved.length === 0) {
         console.log("  Already up to date — no changes.\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overscore/cli",
-  "version": "0.13.15",
+  "version": "0.13.17",
   "description": "CLI for deploying Overscore dashboards and publishing analyses",
   "bin": {
     "overscore": "dist/index.js"