dogsbay 0.2.0-beta.2 → 0.2.0-beta.20

package/dist/commands/agent.js

@@ -0,0 +1,305 @@
+/**
+ * `dogsbay agent install` — wire skill discovery for an LLM agent
+ * (Claude Code, Cursor, Copilot, etc.).
+ *
+ * Bundled platform skills live at `<cli-install-dir>/skills/platform/*.md`.
+ * This command:
+ *   1. Resolves the bundled platform skills directory.
+ *   2. Symlinks them into `<project>/.dogsbay/skills/platform/`.
+ *   3. Creates `.dogsbay/skills/site/` (empty + README) and
+ *      `.dogsbay/skills/plugins/` (empty placeholder).
+ *   4. For each requested --agent, writes the per-agent discovery
+ *      path (`.claude/skills/dogsbay/`, `.cursor/rules/dogsbay/`).
+ *
+ * Re-running is idempotent — symlinks are recreated; existing
+ * site/ files are never touched.
+ *
+ * See plans/dogsbay-agent-skills.md for the four-tier ownership
+ * model and how this fits.
+ */
+import { existsSync, lstatSync, mkdirSync, readdirSync, symlinkSync, unlinkSync, writeFileSync, statSync, readlinkSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import pc from "picocolors";
+const SUPPORTED_AGENTS = ["claude", "cursor"];
+const AGENT_TARGETS = {
+    claude: {
+        name: "claude",
+        skillsDir: ".claude/skills",
+        label: "Claude Code",
+    },
+    cursor: {
+        name: "cursor",
+        skillsDir: ".cursor/rules",
+        label: "Cursor",
+    },
+};
+/**
+ * Prefix every Dogsbay-shipped skill so it doesn't collide with
+ * the user's own skills under the same agent's discovery path.
+ */
+const PLATFORM_PREFIX = "dogsbay-";
+const SITE_PREFIX = "dogsbay-site-";
+const PLUGIN_PREFIX = "dogsbay-plugin-";
+export async function agentInstall(cwd, options) {
+    const projectRoot = resolve(cwd || ".");
+    // Resolve the bundled platform-skills directory. We're running
+    // from <cli-install>/dist/commands/agent.js, so walk up to
+    // <cli-install>/skills/platform/.
+    const here = dirname(fileURLToPath(import.meta.url));
+    const platformSkills = resolve(here, "..", "..", "skills", "platform");
+    if (!existsSync(platformSkills)) {
+        console.error(pc.red(`Error: bundled platform skills not found at ${platformSkills}.`));
+        console.error(`       The dogsbay CLI install seems incomplete. Reinstall with`);
+        console.error(`       'npm install -g dogsbay@latest'.`);
+        process.exit(1);
+    }
+    // Pick the agents to install.
+    const agents = pickAgents(options);
+    if (agents.length === 0) {
+        printDetected(projectRoot);
+        return;
+    }
+    console.log(pc.cyan("→ Installing skill discovery"));
+    // 1. Always set up .dogsbay/skills/{platform,site,plugins}.
+    const dogsbayDir = join(projectRoot, ".dogsbay");
+    const skillsDir = join(dogsbayDir, "skills");
+    mkdirSync(skillsDir, { recursive: true });
+    const platformLink = join(skillsDir, "platform");
+    refreshSymlink(platformLink, platformSkills);
+    console.log(pc.green(`  ✓ ${relative(projectRoot, platformLink)} → bundled platform skills`));
+    const siteDir = join(skillsDir, "site");
+    if (!existsSync(siteDir)) {
+        mkdirSync(siteDir, { recursive: true });
+        writeFileSync(join(siteDir, "README.md"), `# Site skills
+
+This directory holds **site-specific** skills — your team's style
+guide, voice / tone, terminology, glossary, internal conventions.
+Anything an LLM should know that's specific to THIS site.
+
+Each skill is a single \`.md\` file with frontmatter:
+
+\`\`\`markdown
+---
+name: site:style-guide
+description: Our team's writing voice, terminology, and PR conventions.
+---
+
+# Style guide
+
+We use Oxford commas. Sentence-case headings. ...
+\`\`\`
+
+These skills are picked up automatically by any agent you've
+installed via \`dogsbay agent install --agent <name>\`.
+
+To override a platform skill (e.g. a different opinion on
+\`nav-file.md\`), put your version under \`overrides/<skill-name>.md\`.
+The agent loader checks overrides first.
+`);
+        console.log(pc.green(`  ✓ ${relative(projectRoot, siteDir)} created (empty + README)`));
+    }
+    else {
+        console.log(pc.gray(`  · ${relative(projectRoot, siteDir)} already exists (preserved)`));
+    }
+    const pluginsDir = join(skillsDir, "plugins");
+    if (!existsSync(pluginsDir)) {
+        mkdirSync(pluginsDir, { recursive: true });
+    }
+    // 2. Per-agent discovery — symlink each skill INDIVIDUALLY at
+    // the top level of the agent's skills dir. Claude Code (and
+    // similar harnesses) discover skills as direct children of
+    // .claude/skills/, each containing a SKILL.md. Nested
+    // .claude/skills/dogsbay/platform/<skill>/ doesn't get scanned.
+    for (const agent of agents) {
+        const target = AGENT_TARGETS[agent];
+        const agentSkillsDir = join(projectRoot, target.skillsDir);
+        mkdirSync(agentSkillsDir, { recursive: true });
+        let installed = 0;
+        let removed = 0;
+        // Platform skills: dogsbay-<name>
+        for (const entry of readSkillDirs(join(skillsDir, "platform"))) {
+            const dest = join(agentSkillsDir, `${PLATFORM_PREFIX}${entry.name}`);
+            refreshSymlink(dest, entry.path);
+            installed++;
+        }
+        // Site skills: dogsbay-site-<name> (skipping overrides/ and the README)
+        for (const entry of readSkillDirs(join(skillsDir, "site"))) {
+            if (entry.name === "overrides")
+                continue;
+            const dest = join(agentSkillsDir, `${SITE_PREFIX}${entry.name}`);
+            refreshSymlink(dest, entry.path);
+            installed++;
+        }
+        // Plugin skills: dogsbay-plugin-<name>
+        for (const entry of readSkillDirs(join(skillsDir, "plugins"))) {
+            const dest = join(agentSkillsDir, `${PLUGIN_PREFIX}${entry.name}`);
+            refreshSymlink(dest, entry.path);
+            installed++;
+        }
+        // Sweep any stale dogsbay-* symlinks whose target no longer
+        // exists (e.g. user uninstalled a plugin, or a platform skill
+        // was renamed across CLI versions).
+        if (existsSync(agentSkillsDir)) {
+            for (const name of readdirSync(agentSkillsDir)) {
+                if (!name.startsWith("dogsbay-"))
+                    continue;
+                const path = join(agentSkillsDir, name);
+                if (isBrokenSymlink(path)) {
+                    try {
+                        unlinkSync(path);
+                        removed++;
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+        }
+        console.log(pc.green(`  ✓ ${target.label}: ${installed} skills under ${target.skillsDir}/`));
+        if (removed > 0) {
+            console.log(pc.gray(`    (cleaned up ${removed} stale symlink${removed === 1 ? "" : "s"})`));
+        }
+    }
+    console.log("");
+    console.log(pc.cyan("Next:"));
+    console.log("  Open your editor — the agent should now see Dogsbay platform skills");
+    console.log("  on next prompt.");
+    console.log("");
+    console.log("  Add team-specific skills to .dogsbay/skills/site/.");
+    console.log("  Override a platform skill with .dogsbay/skills/site/overrides/<name>.md.");
+}
+/**
+ * Decide which agents to set up. Priority:
+ *   --all → every supported agent
+ *   --agent claude,cursor → exactly that list
+ *   neither → return [], caller prints detected agents and exits
+ */
+function pickAgents(options) {
+    if (options.all)
+        return [...SUPPORTED_AGENTS];
+    if (options.agent) {
+        const requested = options.agent.split(",").map((a) => a.trim().toLowerCase());
+        const valid = [];
+        for (const r of requested) {
+            if (SUPPORTED_AGENTS.includes(r)) {
+                valid.push(r);
+            }
+            else {
+                console.error(pc.yellow(`  warn: unknown agent "${r}" (supported: ${SUPPORTED_AGENTS.join(", ")})`));
+            }
+        }
+        return valid;
+    }
+    return [];
+}
+/**
+ * When called without --agent or --all, just probe the project
+ * for known agent-config dirs and suggest commands.
+ */
+function printDetected(projectRoot) {
+    const detected = [];
+    if (existsSync(join(projectRoot, ".claude"))) {
+        detected.push({ agent: "claude", signal: ".claude/" });
+    }
+    if (existsSync(join(projectRoot, ".cursor")) ||
+        existsSync(join(projectRoot, ".cursorrules"))) {
+        detected.push({ agent: "cursor", signal: ".cursor/ or .cursorrules" });
+    }
+    console.log(pc.cyan("Dogsbay agent install"));
+    console.log("");
+    console.log("Wires Dogsbay platform skills into the discovery path of an");
+    console.log("LLM agent so it picks them up on every prompt.");
+    console.log("");
+    if (detected.length > 0) {
+        console.log(pc.green("Detected in this project:"));
+        for (const d of detected) {
+            console.log(`  ${d.agent.padEnd(8)} (${d.signal})`);
+        }
+        console.log("");
+        console.log("Run:");
+        for (const d of detected) {
+            console.log(`  dogsbay agent install --agent ${d.agent}`);
+        }
+        console.log("  dogsbay agent install --all      # set up every detected agent");
+    }
+    else {
+        console.log(pc.yellow("No supported agent configs detected in this project."));
+        console.log("");
+        console.log("Run:");
+        console.log("  dogsbay agent install --agent claude");
+        console.log("  dogsbay agent install --agent cursor");
+        console.log("  dogsbay agent install --all");
+    }
+    console.log("");
+    console.log(`Supported agents: ${SUPPORTED_AGENTS.join(", ")}`);
+}
+/**
+ * List each subdirectory of `dir` that looks like a skill — i.e.
+ * contains a SKILL.md file. Returns an empty array if `dir`
+ * doesn't exist or has no skill subdirs.
+ */
+function readSkillDirs(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const name of readdirSync(dir)) {
+        if (name.startsWith("."))
+            continue;
+        const path = join(dir, name);
+        let isDir = false;
+        try {
+            isDir = statSync(path).isDirectory();
+        }
+        catch {
+            isDir = false;
+        }
+        if (!isDir)
+            continue;
+        if (!existsSync(join(path, "SKILL.md")))
+            continue;
+        out.push({ name, path });
+    }
+    return out;
+}
+/**
+ * Replace any existing entry at `linkPath` with a fresh symlink
+ * pointing at `target`. Idempotent: if the link already points at
+ * the right place, leaves it alone.
+ */
+function refreshSymlink(linkPath, target) {
+    if (existsSync(linkPath) || isBrokenSymlink(linkPath)) {
+        try {
+            const current = readlinkSync(linkPath);
+            const resolved = resolve(dirname(linkPath), current);
+            if (resolved === target)
+                return; // already correct
+        }
+        catch {
+            // not a symlink
+        }
+        try {
+            unlinkSync(linkPath);
+        }
+        catch {
+            // ignore
+        }
+    }
+    symlinkSync(target, linkPath, "dir");
+}
+/**
+ * True only when `p` IS a symlink AND its target doesn't exist.
+ * Used by the cleanup pass to remove links pointing at gone paths
+ * (e.g. an uninstalled plugin or a renamed platform skill across
+ * CLI versions).
+ */
+function isBrokenSymlink(p) {
+    try {
+        const lst = lstatSync(p);
+        if (!lst.isSymbolicLink())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    // It's a symlink. existsSync follows the link; false → target gone.
+    return !existsSync(p);
+}

package/dist/commands/site-build.js

@@ -17,7 +17,8 @@
 import { existsSync } from "node:fs";
 import { dirname, isAbsolute, resolve } from "node:path";
 import pc from "picocolors";
-import { emitAstroPages, emitSiteConfig, emitConfigDerivedFiles, emitAgentReadinessFiles, emitMissingTranslationStubs, emitSwitcherMap, emitTaxonomyRoutes, emitPluginRuntime, normalizeBasePath, basePathSegments, } from "@dogsbay/format-astro";
+import { emitAstroPages, emitPassthroughAstroPages, emitSiteConfig, emitConfigDerivedFiles, emitDeployArtifacts, emitAgentReadinessFiles, emitMissingTranslationStubs, emitSwitcherMap, emitTaxonomyRoutes, emitPluginRuntime, normalizeBasePath, basePathSegments, resolvePrefixes, } from "@dogsbay/format-astro";
+import { collectPassthroughEntries } from "../passthrough-astro.js";
 import { configToAstroOptions, findConfig, loadConfig, resolveOutputDir, } from "../config/index.js";
 import { filterSourcesForMode, importContent, primaryModeFiltersAnything, } from "../import-content.js";
 import { resolveSource } from "../source-resolver.js";
@@ -66,11 +67,21 @@ export async function siteBuild(cwd, options) {
         console.error(`       Run \`dogsbay site init ${siteRoot}\` first.`);
         process.exit(1);
     }
-    // 5. Filter to primary sources (default) or load full matrix
-    // (--publish). Primary-only is the fast path local iteration
-    // and CI lint jobs use; --publish builds everything for the
-    // deploy job. See plans/multi-source-content.md → "Build modes".
-    const mode = options.publish ? "all" : "primary";
+    // 5. Default to publish mode (every declared source builds) so
+    // multi-locale / multi-version / multi-namespace sites Just Work
+    // when the writer runs `dogsbay site build`. Use --primary-only
+    // for fast-iteration CI jobs that don't need the full matrix
+    // (rare). The `--publish` flag is kept as a deprecated no-op for
+    // older scripts.
+    //
+    // Previous default was "primary-only" — silently dropped non-
+    // primary sources from production builds. With i18n and version
+    // axes, that meant declaring `locales:` resulted in only the
+    // English source shipping, surprising every writer who ran
+    // `dogsbay site build` after declaring fr. Inverted to match the
+    // strongest signal: declaring more sources means you want them
+    // all. See plans/beta-launch-followups.md.
+    const mode = options.primaryOnly ? "primary" : "all";
     const originalSources = config.content.sources;
     const totalSources = originalSources.length;
     const { sources: activeSources, indices: activeIndices } = filterSourcesForMode(originalSources, mode);
@@ -156,12 +167,45 @@ export async function siteBuild(cwd, options) {
     // generalize this to copy assets per-source.
     const astroOpts = configToAstroOptions(config);
     astroOpts.sourceDir = resolvedSources[0];
+    // siteRoot = repo root (where dogsbay.config.yml lives). Used by
+    // emitDeployArtifacts to drop GH Actions workflows at
+    // <siteRoot>/.github/ rather than inside the Astro subdir, where
+    // GitHub wouldn't find them.
+    astroOpts.projectDir = siteRoot;
     // Refresh src/data/site.json from the current config — purely
     // config-derived, so changes in dogsbay.config.yml propagate without
     // re-running site init.
     emitSiteConfig(outputDir, config.site.name, astroOpts);
-    const { generated, outputNav } = await emitAstroPages(pages, nav, outputDir, astroOpts);
+    const { generated, outputNav, generatedPaths } = await emitAstroPages(pages, nav, outputDir, astroOpts);
+    // Passthrough Astro pages — hand-authored .astro files that live
+    // alongside the markdown sources and are listed in nav.yml. Picked
+    // up by walking the source directories for *.astro and intersecting
+    // with the resolved nav hrefs. Collisions with generated pages are
+    // a build error (loud, not silent overwrite). See
+    // plans/passthrough-astro-pages.md.
+    const passthroughCopies = [];
+    for (const sourceDir of resolvedSources) {
+        const entries = collectPassthroughEntries(sourceDir, outputNav, {
+            basePath: normalizeBasePath(astroOpts.basePath),
+        });
+        for (const entry of entries) {
+            passthroughCopies.push({
+                source: entry.source,
+                sourceAbs: entry.sourceAbs,
+                outputRelPath: entry.outputRelPath,
+            });
+        }
+    }
+    if (passthroughCopies.length > 0) {
+        const { copied } = emitPassthroughAstroPages(passthroughCopies, outputDir, generatedPaths);
+        console.log(`  Copied ${copied} passthrough .astro page${copied === 1 ? "" : "s"}`);
+    }
     emitConfigDerivedFiles(outputDir, astroOpts);
+    // Deploy artifacts — write-if-missing so adding `deploy: github-pages`
+    // to dogsbay.config.yml on an existing site materializes the workflow
+    // on the next build. Author edits survive (only fired when the file
+    // doesn't exist; --force regeneration goes through site init).
+    emitDeployArtifacts(outputDir, astroOpts);
     emitAgentReadinessFiles(pages, outputNav, outputDir, config.site.name, astroOpts);
     // switcherMap.json — per-page version-equivalent lookup. No-op
     // when the version axis isn't active; cleans up a stale file
@@ -206,9 +250,13 @@ export async function siteBuild(cwd, options) {
                 labels: raw.labels,
             };
         }
+        // Pass the combined prefix as basePath to taxonomy — term URLs
+        // need to include both urlBase (host subpath) and dogsbay
+        // basePath so they resolve correctly under the served URL.
+        const taxoCombined = resolvePrefixes(config.site.url, config.site.basePath).combined;
         const emitted = emitTaxonomyRoutes(pages, outputDir, taxonomyConfigs, {
             section: config.content.section,
-            basePath: config.site.basePath,
+            basePath: taxoCombined,
         });
         if (emitted.length > 0) {
             console.log(`  Emitted taxonomy routes: ${emitted.join(", ")}`);
@@ -231,16 +279,16 @@ export async function siteBuild(cwd, options) {
         console.warn(`  Copy markdown + View as markdown work without it.`);
     }
     console.log(pc.green(`\nDone! Built ${generated} pages into ${outputDir}`));
-    // When the writer has marked some sources as primary and we
-    // built only those, surface the --publish hint. Skip the hint
-    // for plain single-source builds and for full --publish runs
-    // — both already build everything.
+    // When the writer ran with --primary-only and we filtered the
+    // matrix, surface a hint that drops them back to the default.
+    // Skip for single-source / full-matrix builds — both already
+    // built everything.
     if (mode === "primary" && primaryModeFiltersAnything(originalSources)) {
         const skipped = totalSources - activeIndices.length;
         console.log("");
-        console.log(pc.dim(`Built ${activeIndices.length} primary source(s); ` +
-            `${skipped} non-primary skipped. ` +
-            `Run \`dogsbay site build --publish\` for the full matrix.`));
+        console.log(pc.dim(`--primary-only built ${activeIndices.length} of ${totalSources} ` +
+            `sources; ${skipped} non-primary skipped. ` +
+            `Drop --primary-only to build the full matrix.`));
     }
     console.log("");
     console.log(pc.cyan("Next:"));
@@ -315,6 +363,9 @@ function mergeOverrides(config, opts) {
     if (opts.deploy === "cloudflare-workers") {
         next.deploy = { target: "cloudflare-workers" };
     }
+    else if (opts.deploy === "github-pages") {
+        next.deploy = { target: "github-pages" };
+    }
     // Analytics
     if (opts.plausibleDomain) {
         next.analytics = next.analytics ?? {};