@marlinjai/clearify 1.20.0 → 2.0.0

package/dist/config-schema.json

@@ -116,9 +116,6 @@
               "description": {
                 "type": "string"
               },
-              "href": {
-                "type": "string"
-              },
               "repo": {
                 "type": "string"
               },
@@ -144,64 +141,165 @@
               "group": {
                 "type": "string"
               },
-              "mode": {
-                "type": "string",
-                "enum": [
-                  "link",
-                  "embed",
-                  "inject"
-                ]
-              },
-              "git": {
-                "type": "object",
-                "properties": {
-                  "repo": {
-                    "type": "string"
+              "source": {
+                "oneOf": [
+                  {
+                    "type": "object",
+                    "properties": {
+                      "kind": {
+                        "type": "string",
+                        "const": "none"
+                      }
+                    },
+                    "required": [
+                      "kind"
+                    ],
+                    "additionalProperties": false
                   },
-                  "ref": {
-                    "type": "string"
+                  {
+                    "type": "object",
+                    "properties": {
+                      "kind": {
+                        "type": "string",
+                        "const": "git"
+                      },
+                      "repo": {
+                        "type": "string"
+                      },
+                      "ref": {
+                        "type": "string"
+                      },
+                      "path": {
+                        "type": "string"
+                      },
+                      "sparse": {
+                        "type": "boolean"
+                      }
+                    },
+                    "required": [
+                      "kind",
+                      "repo"
+                    ],
+                    "additionalProperties": false
                   },
-                  "path": {
-                    "type": "string"
+                  {
+                    "type": "object",
+                    "properties": {
+                      "kind": {
+                        "type": "string",
+                        "const": "url"
+                      },
+                      "url": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "kind",
+                      "url"
+                    ],
+                    "additionalProperties": false
                   },
-                  "sparse": {
-                    "type": "boolean"
+                  {
+                    "type": "object",
+                    "properties": {
+                      "kind": {
+                        "type": "string",
+                        "const": "inline"
+                      },
+                      "markdown": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "kind",
+                      "markdown"
+                    ],
+                    "additionalProperties": false
                   }
-                },
-                "required": [
-                  "repo"
-                ],
-                "additionalProperties": false
+                ]
               },
-              "embedSections": {
-                "anyOf": [
+              "placement": {
+                "oneOf": [
                   {
-                    "type": "string",
-                    "const": "all"
+                    "type": "object",
+                    "properties": {
+                      "kind": {
+                        "type": "string",
+                        "const": "card"
+                      },
+                      "href": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "kind",
+                      "href"
+                    ],
+                    "additionalProperties": false
                   },
                   {
-                    "type": "string",
-                    "const": "public"
+                    "type": "object",
+                    "properties": {
+                      "kind": {
+                        "type": "string",
+                        "const": "tab"
+                      },
+                      "sections": {
+                        "anyOf": [
+                          {
+                            "type": "string",
+                            "const": "all"
+                          },
+                          {
+                            "type": "string",
+                            "const": "public"
+                          },
+                          {
+                            "type": "array",
+                            "items": {
+                              "type": "string"
+                            }
+                          }
+                        ]
+                      }
+                    },
+                    "required": [
+                      "kind"
+                    ],
+                    "additionalProperties": false
                   },
                   {
-                    "type": "array",
-                    "items": {
-                      "type": "string"
-                    }
+                    "type": "object",
+                    "properties": {
+                      "kind": {
+                        "type": "string",
+                        "const": "nested"
+                      },
+                      "into": {
+                        "type": "string"
+                      },
+                      "docsPath": {
+                        "type": "string"
+                      },
+                      "group": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "kind",
+                      "into"
+                    ],
+                    "additionalProperties": false
                   }
                 ]
-              },
-              "injectInto": {
-                "type": "string"
-              },
-              "docsPath": {
-                "type": "string"
               }
             },
             "required": [
               "name",
               "description",
-              "status"
+              "status",
+              "source",
+              "placement"
             ],
             "additionalProperties": false
           }

package/dist/node/{chunk-XR4WG237.js → chunk-BCEGDIR6.js}

@@ -8,12 +8,12 @@ import {
 } from "./chunk-SCZZB7OE.js";
 import {
   clearifyPlugin
-} from "./chunk-GWYMXKDL.js";
+} from "./chunk-RW4IKHY4.js";
 import {
   loadUserConfig,
   resolveConfig,
   resolveSections
-} from "./chunk-2WML2D77.js";
+} from "./chunk-PGTNVDNF.js";
 import {
   buildSectionData
 } from "./chunk-CTL4YL7C.js";

package/dist/node/{chunk-HZRIVY25.js → chunk-CK2SLBAG.js}

@@ -2,7 +2,7 @@ import {
   loadUserConfig,
   resolveConfig,
   resolveSections
-} from "./chunk-2WML2D77.js";
+} from "./chunk-PGTNVDNF.js";
 import {
   scanDocs
 } from "./chunk-CTL4YL7C.js";

package/dist/node/{chunk-JZZ2BNIL.js → chunk-GPBEDIOY.js}

@@ -282,7 +282,7 @@ ${hasInternal ? `
 `);
   const secretMode = options.secretMode ?? "prompt";
   if (options.hub) {
-    const { registerWithHub } = await import("./hub-register-7NF5BP3E.js");
+    const { registerWithHub } = await import("./hub-register-QB73GUF2.js");
     await registerWithHub({
       projectName: detectProjectName(),
       hubToken: options.hubToken,
@@ -298,7 +298,7 @@ ${hasInternal ? `
     });
     rl.close();
     if (answer.toLowerCase() === "y") {
-      const { registerWithHub } = await import("./hub-register-7NF5BP3E.js");
+      const { registerWithHub } = await import("./hub-register-QB73GUF2.js");
       await registerWithHub({
         projectName: detectProjectName(),
         hubToken: options.hubToken,

package/dist/node/{chunk-2WML2D77.js → chunk-PGTNVDNF.js}

@@ -42,28 +42,44 @@ var OpenAPIConfigSchema = z.object({
   basePath: z.string().default("/api"),
   generatePages: z.boolean().default(true)
 }).optional();
+var HubProjectSourceSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("none") }),
+  z.object({
+    kind: z.literal("git"),
+    repo: z.string(),
+    ref: z.string().optional(),
+    path: z.string().optional(),
+    sparse: z.boolean().optional()
+  }),
+  z.object({ kind: z.literal("url"), url: z.string() }),
+  z.object({ kind: z.literal("inline"), markdown: z.string() })
+]);
+var HubProjectPlacementSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("card"), href: z.string() }),
+  z.object({
+    kind: z.literal("tab"),
+    sections: z.union([z.literal("all"), z.literal("public"), z.array(z.string())]).optional()
+  }),
+  z.object({
+    kind: z.literal("nested"),
+    into: z.string(),
+    docsPath: z.string().optional(),
+    group: z.string().optional()
+  })
+]);
 var HubProjectSchema = z.object({
   name: z.string(),
   description: z.string(),
-  href: z.string().optional(),
   repo: z.string().optional(),
   status: z.enum(["active", "beta", "planned", "deprecated"]).default("active"),
   icon: z.string().optional(),
   tags: z.array(z.string()).optional(),
   group: z.string().optional(),
-  mode: z.enum(["link", "embed", "inject"]).optional(),
-  git: RemoteGitSourceSchema.optional(),
-  embedSections: z.union([
-    z.literal("all"),
-    z.literal("public"),
-    z.array(z.string())
-  ]).optional(),
-  injectInto: z.string().optional(),
-  docsPath: z.string().optional()
+  source: HubProjectSourceSchema,
+  placement: HubProjectPlacementSchema
 });
 var HubProjectPartialSchema = z.object({
   description: z.string(),
-  href: z.string().optional(),
   repo: z.string().optional(),
   status: z.enum(["active", "beta", "planned", "deprecated"]).default("active"),
   icon: z.string().optional(),
@@ -335,8 +351,14 @@ function buildStagingOverlay(stagingDir, originalDir, injections) {
     symlinkSync(sourcePath, destPath);
   }
 }
+function isReservedSource(source) {
+  return source.kind === "url" || source.kind === "inline";
+}
 async function scanHubProjects(config, root) {
-  if (!config.hub?.scan && !config.hub?.projects?.some((p) => p.mode === "embed" || p.mode === "inject")) {
+  const hasGitTabOrNested = config.hub?.projects?.some(
+    (p) => p.source.kind === "git" && (p.placement.kind === "tab" || p.placement.kind === "nested")
+  ) ?? false;
+  if (!config.hub?.scan && !hasGitTabOrNested) {
     return config;
   }
   const scannedProjects = [];
@@ -350,15 +372,17 @@ async function scanHubProjects(config, root) {
         if (!childConfig.hubProject) continue;
         const name = childConfig.name ?? basename(dirname(configPath));
         const hp = childConfig.hubProject;
+        const href = childConfig.siteUrl;
         scannedProjects.push({
           name,
           description: hp.description,
-          href: hp.href ?? childConfig.siteUrl,
           repo: hp.repo,
           status: hp.status,
           icon: hp.icon,
           tags: hp.tags,
-          group: hp.group
+          group: hp.group,
+          source: { kind: "none" },
+          placement: { kind: "card", href: href ?? "#" }
         });
       } catch {
       }
@@ -369,18 +393,26 @@ async function scanHubProjects(config, root) {
     ...scannedProjects.filter((p) => !manualNames.has(p.name)),
     ...config.hub?.projects ?? []
   ];
+  for (const project of merged) {
+    if (isReservedSource(project.source)) {
+      throw new Error(
+        `Hub project "${project.name}": source.kind "${project.source.kind}" is reserved and not implemented. Use source.kind "none" or "git".`
+      );
+    }
+  }
   const embedSections = [];
   for (const project of merged) {
-    if (project.mode !== "embed" || !project.git) continue;
+    if (project.source.kind !== "git" || project.placement.kind !== "tab") continue;
     const cacheDir = config.hub?.cacheDir ? resolve(root, config.hub.cacheDir) : resolve(root, "node_modules/.cache/clearify-remote");
     try {
       const { resolveRemoteSource } = await import("./core/remote.js");
-      const { localPath } = await resolveRemoteSource(project.git, cacheDir);
+      const { kind: _kind, ...gitSource } = project.source;
+      const { localPath } = await resolveRemoteSource(gitSource, cacheDir);
       const remoteConfig = await loadUserConfig(localPath);
       const remoteSections = remoteConfig.sections ?? [
         { label: remoteConfig.name ?? project.name, docsDir: remoteConfig.docsDir ?? "./docs" }
       ];
-      const filter = project.embedSections ?? "public";
+      const filter = project.placement.sections ?? "public";
       const filtered = remoteSections.filter((s) => {
         if (filter === "all") return true;
         if (filter === "public") return !s.draft;
@@ -400,46 +432,44 @@ async function scanHubProjects(config, root) {
           exclude: s.exclude
         });
       }
-      console.log(`  Hub embed "${project.name}": ${filtered.length} sections pulled`);
+      console.log(`  Hub tab "${project.name}": ${filtered.length} sections pulled`);
     } catch (err) {
       console.warn(
-        `  \u26A0 Hub embed "${project.name}" failed:`,
+        `  Hub tab "${project.name}" failed:`,
         err instanceof Error ? err.message : err
       );
     }
   }
   const injectionsBySection = /* @__PURE__ */ new Map();
   for (const project of merged) {
-    if (project.mode !== "inject" || !project.git) continue;
+    if (project.source.kind !== "git" || project.placement.kind !== "nested") continue;
     const cacheDir = config.hub?.cacheDir ? resolve(root, config.hub.cacheDir) : resolve(root, "node_modules/.cache/clearify-remote");
     try {
       const { resolveRemoteSource } = await import("./core/remote.js");
-      const { localPath, cached } = await resolveRemoteSource(project.git, cacheDir);
-      const docsPath = project.docsPath ?? "docs";
+      const { kind: _kind, ...gitSource } = project.source;
+      const { localPath, cached } = await resolveRemoteSource(gitSource, cacheDir);
+      const docsPath = project.placement.docsPath ?? "docs";
       const absoluteDocsPath = resolve(localPath, docsPath);
       if (!existsSync(absoluteDocsPath)) {
         console.warn(
-          `  \u26A0 Hub inject "${project.name}": docs path "${docsPath}" not found in cloned repo.`
+          `  Hub nested "${project.name}": docs path "${docsPath}" not found in cloned repo.`
         );
         continue;
       }
-      const targetLabel = project.injectInto;
-      if (!targetLabel) {
-        console.warn(`  \u26A0 Hub inject "${project.name}": missing injectInto field.`);
-        continue;
-      }
+      const targetLabel = project.placement.into;
       if (!injectionsBySection.has(targetLabel)) {
         injectionsBySection.set(targetLabel, /* @__PURE__ */ new Map());
       }
       const slugifiedName = slugify(project.name);
-      const relPath = project.group ? `projects/${project.group}/${slugifiedName}` : `projects/${slugifiedName}`;
+      const groupSeg = project.placement.group;
+      const relPath = groupSeg ? `projects/${groupSeg}/${slugifiedName}` : `projects/${slugifiedName}`;
       injectionsBySection.get(targetLabel).set(relPath, absoluteDocsPath);
       console.log(
-        `  Hub inject "${project.name}": ${cached ? "cached" : "cloned"} \u2192 ${relPath}`
+        `  Hub nested "${project.name}": ${cached ? "cached" : "cloned"} to ${relPath}`
       );
     } catch (err) {
       console.warn(
-        `  \u26A0 Hub inject "${project.name}" failed:`,
+        `  Hub nested "${project.name}" failed:`,
         err instanceof Error ? err.message : err
       );
     }

package/dist/node/{chunk-GWYMXKDL.js → chunk-RW4IKHY4.js}

@@ -10,7 +10,7 @@ import {
   resolveSections,
   scanHubProjects,
   writeDataConfig
-} from "./chunk-2WML2D77.js";
+} from "./chunk-PGTNVDNF.js";
 import {
   buildSectionData
 } from "./chunk-CTL4YL7C.js";

package/dist/node/core/config.d.ts

@@ -37,7 +37,6 @@ declare const ClearifyDataSchema: z.ZodObject<{
         projects: z.ZodDefault<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
             description: z.ZodString;
-            href: z.ZodOptional<z.ZodString>;
             repo: z.ZodOptional<z.ZodString>;
             status: z.ZodDefault<z.ZodEnum<{
                 active: "active";
@@ -48,20 +47,33 @@ declare const ClearifyDataSchema: z.ZodObject<{
             icon: z.ZodOptional<z.ZodString>;
             tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
             group: z.ZodOptional<z.ZodString>;
-            mode: z.ZodOptional<z.ZodEnum<{
-                link: "link";
-                embed: "embed";
-                inject: "inject";
-            }>>;
-            git: z.ZodOptional<z.ZodObject<{
+            source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"none">;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"git">;
                 repo: z.ZodString;
                 ref: z.ZodOptional<z.ZodString>;
                 path: z.ZodOptional<z.ZodString>;
                 sparse: z.ZodOptional<z.ZodBoolean>;
-            }, z.core.$strip>>;
-            embedSections: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodLiteral<"public">, z.ZodArray<z.ZodString>]>>;
-            injectInto: z.ZodOptional<z.ZodString>;
-            docsPath: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"url">;
+                url: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                markdown: z.ZodString;
+            }, z.core.$strip>], "kind">;
+            placement: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"card">;
+                href: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"tab">;
+                sections: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodLiteral<"public">, z.ZodArray<z.ZodString>]>>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"nested">;
+                into: z.ZodString;
+                docsPath: z.ZodOptional<z.ZodString>;
+                group: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>], "kind">;
         }, z.core.$strip>>>;
         scan: z.ZodOptional<z.ZodString>;
         cacheDir: z.ZodOptional<z.ZodString>;

package/dist/node/core/config.js

@@ -8,7 +8,7 @@ import {
   resolveSections,
   scanHubProjects,
   writeDataConfig
-} from "../chunk-2WML2D77.js";
+} from "../chunk-PGTNVDNF.js";
 import "../chunk-AJBCHKBP.js";
 import {
   defineConfig

package/dist/node/{hub-register-7NF5BP3E.js → hub-register-QB73GUF2.js}

@@ -79,6 +79,7 @@ async function secretExists(token, owner, repo, name) {
   const res = await ghApiFetch(url, { headers: { Authorization: `token ${token}` } });
   return res.status === 200;
 }
+var __internal = { encryptSecret };
 async function promptSecretMode() {
   const { createInterface } = await import("readline");
   const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -212,12 +213,13 @@ async function updateHubRegistry(token, hub, project) {
     name: project.name,
     description: project.description,
     status: "active",
-    mode: "embed",
-    git: {
+    source: {
+      kind: "git",
       repo: project.gitRepoUrl,
       ref: project.gitRef,
       path: project.docsPath
-    }
+    },
+    placement: { kind: "tab" }
   };
   if (existingIdx >= 0) {
     currentData.hub.projects[existingIdx] = entry;
@@ -396,5 +398,6 @@ function printSuccessFooter(currentRepo) {
 `);
 }
 export {
+  __internal,
   registerWithHub
 };

package/dist/node/node/build.js

@@ -1,11 +1,11 @@
 import {
   buildSite
-} from "../chunk-XR4WG237.js";
+} from "../chunk-BCEGDIR6.js";
 import "../chunk-PRTER35L.js";
 import "../chunk-SCZZB7OE.js";
-import "../chunk-GWYMXKDL.js";
+import "../chunk-RW4IKHY4.js";
 import "../chunk-B2Q23JW3.js";
-import "../chunk-2WML2D77.js";
+import "../chunk-PGTNVDNF.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
 import "../chunk-CTL4YL7C.js";

package/dist/node/node/check.js

@@ -1,8 +1,8 @@
 import {
   checkFrontmatter,
   checkLinks
-} from "../chunk-HZRIVY25.js";
-import "../chunk-2WML2D77.js";
+} from "../chunk-CK2SLBAG.js";
+import "../chunk-PGTNVDNF.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
 import "../chunk-CTL4YL7C.js";

package/dist/node/node/index.js

@@ -1,25 +1,25 @@
 import {
   buildSite
-} from "../chunk-XR4WG237.js";
+} from "../chunk-BCEGDIR6.js";
 import {
   remarkMermaidToComponent
 } from "../chunk-PRTER35L.js";
 import "../chunk-SCZZB7OE.js";
 import {
   clearifyPlugin
-} from "../chunk-GWYMXKDL.js";
+} from "../chunk-RW4IKHY4.js";
 import "../chunk-B2Q23JW3.js";
 import {
   init
-} from "../chunk-JZZ2BNIL.js";
+} from "../chunk-GPBEDIOY.js";
 import {
   checkFrontmatter,
   checkLinks
-} from "../chunk-HZRIVY25.js";
+} from "../chunk-CK2SLBAG.js";
 import {
   loadUserConfig,
   resolveConfig
-} from "../chunk-2WML2D77.js";
+} from "../chunk-PGTNVDNF.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
 import "../chunk-CTL4YL7C.js";

package/dist/node/node/init.js

@@ -1,6 +1,6 @@
 import {
   init
-} from "../chunk-JZZ2BNIL.js";
+} from "../chunk-GPBEDIOY.js";
 export {
   init
 };

package/dist/node/types/index.d.ts

@@ -58,7 +58,7 @@ interface ClearifyConfig {
         [key: string]: string | undefined;
     };
     hub?: HubConfig;
-    hubProject?: Omit<HubProject, 'name'>;
+    hubProject?: HubProjectPartial;
     customCss?: string;
     headTags?: string[];
     includeReadme?: boolean;
@@ -92,10 +92,54 @@ interface RouteEntry {
     componentPath?: string;
     redirectTo?: string;
 }
+/**
+ * Where a hub project's content comes from.
+ *
+ * `none`: no content pulled, card links out only.
+ * `git`: sparse-clone a repo subdirectory.
+ * `url`: reserved for future remote-docs fetch, not implemented.
+ * `inline`: reserved for future inline markdown, not implemented.
+ */
+type HubProjectSource = {
+    kind: 'none';
+} | {
+    kind: 'git';
+    repo: string;
+    /** branch, tag, or SHA. Default: 'main' */
+    ref?: string;
+    /** subdirectory to sparse-checkout. Default: 'docs/public' */
+    path?: string;
+    /** defaults to true when path is set */
+    sparse?: boolean;
+} | {
+    kind: 'url';
+    url: string;
+} | {
+    kind: 'inline';
+    markdown: string;
+};
+/**
+ * How a hub project shows up in the hub UI.
+ *
+ * `card`: grid entry that links to an external href.
+ * `tab`: full tab in the hub nav, rendering the cloned sections.
+ * `nested`: folded into an existing hub section as a subfolder.
+ */
+type HubProjectPlacement = {
+    kind: 'card';
+    href: string;
+} | {
+    kind: 'tab';
+    sections?: 'all' | 'public' | string[];
+} | {
+    kind: 'nested';
+    into: string;
+    docsPath?: string;
+    group?: string;
+};
 interface HubProject {
     name: string;
     description: string;
-    href?: string;
     repo?: string;
     status?: 'active' | 'beta' | 'planned' | 'deprecated';
     icon?: string;
@@ -103,11 +147,25 @@ interface HubProject {
     group?: string;
     hubUrl?: string;
     hubName?: string;
-    mode?: 'link' | 'embed' | 'inject';
-    git?: RemoteGitSource;
-    embedSections?: 'all' | 'public' | string[];
-    injectInto?: string;
-    docsPath?: string;
+    source: HubProjectSource;
+    placement: HubProjectPlacement;
+}
+/**
+ * The subset of HubProject fields a sub-project can declare about itself in
+ * `clearify.config.ts`. The hub scanner composes this with the sub-project's
+ * `siteUrl` and assigns `source` + `placement` on its own side.
+ */
+interface HubProjectPartial {
+    description: string;
+    repo?: string;
+    status?: 'active' | 'beta' | 'planned' | 'deprecated';
+    icon?: string;
+    tags?: string[];
+    group?: string;
+    /** URL of the parent hub site, used by the Sidebar back-link. */
+    hubUrl?: string;
+    /** Display name for the Sidebar back-link. Default: 'Hub'. */
+    hubName?: string;
 }
 interface HubConfig {
     projects: HubProject[];
@@ -135,4 +193,4 @@ interface ClearifyDataConfig {
 }
 declare function defineConfig(config: Partial<ClearifyConfig>): Partial<ClearifyConfig>;
 
-export { type ClearifyConfig, type ClearifyDataConfig, type DocCategory, type HubConfig, type HubProject, type NavigationItem, type PageFrontmatter, type RemoteGitSource, type ResolvedSection, type RouteEntry, type SectionConfig, type SectionNavigation, defineConfig };
+export { type ClearifyConfig, type ClearifyDataConfig, type DocCategory, type HubConfig, type HubProject, type HubProjectPartial, type HubProjectPlacement, type HubProjectSource, type NavigationItem, type PageFrontmatter, type RemoteGitSource, type ResolvedSection, type RouteEntry, type SectionConfig, type SectionNavigation, defineConfig };

package/dist/node/vite-plugin/index.js

@@ -1,8 +1,8 @@
 import {
   clearifyPlugin
-} from "../chunk-GWYMXKDL.js";
+} from "../chunk-RW4IKHY4.js";
 import "../chunk-B2Q23JW3.js";
-import "../chunk-2WML2D77.js";
+import "../chunk-PGTNVDNF.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
 import "../chunk-CTL4YL7C.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marlinjai/clearify",
-  "version": "1.20.0",
+  "version": "2.0.0",
   "description": "An open-source documentation site generator. Turn markdown into beautiful docs.",
   "type": "module",
   "bin": {
@@ -28,7 +28,8 @@
     "postbuild": "node scripts/generate-schema.mjs",
     "dev:self": "node bin/clearify.js dev",
     "prepare": "husky",
-    "release": "semantic-release"
+    "release": "semantic-release",
+    "test": "vitest run"
   },
   "dependencies": {
     "@inquirer/password": "^5.0.11",
@@ -82,7 +83,8 @@
     "puppeteer": "^24.37.2",
     "semantic-release": "^25.0.3",
     "tsup": "^8.3.6",
-    "typescript": "^5.7.3"
+    "typescript": "^5.7.3",
+    "vitest": "^4.1.4"
   },
   "packageManager": "pnpm@9.15.0",
   "license": "MIT",

package/src/theme/Sidebar.tsx

@@ -1,13 +1,13 @@
 import React, { useState, useEffect, useRef } from 'react';
 import { Link, useLocation, useNavigate } from 'react-router-dom';
 import clsx from 'clsx';
-import type { NavigationItem, SectionNavigation, HubProject } from '../types/index.js';
+import type { NavigationItem, SectionNavigation, HubProjectPartial } from '../types/index.js';
 
 interface SidebarProps {
   sections: SectionNavigation[];
   open: boolean;
   onClose: () => void;
-  hubProject?: Omit<HubProject, 'name'>;
+  hubProject?: HubProjectPartial;
 }
 
 function findActiveSection(pathname: string, sections: SectionNavigation[]): string {

package/src/theme/admin/ProjectsManager.tsx

@@ -1,5 +1,5 @@
 import React, { useEffect, useState, useCallback } from 'react';
-import type { HubProject } from '../../types/index.js';
+import type { HubProject, HubProjectSource, HubProjectPlacement } from '../../types/index.js';
 import { Modal } from './components/Modal.js';
 import { ConfirmDialog } from './components/ConfirmDialog.js';
 import { useToast, ToastContainer } from './components/Toast.js';
@@ -16,23 +16,141 @@ const statusColors: Record<string, { bg: string; text: string }> = {
 };
 
 /* ------------------------------------------------------------------ */
-/*  Empty default                                                      */
+/*  Draft form shape                                                   */
 /* ------------------------------------------------------------------ */
-function emptyProject(): HubProject {
+/**
+ * The form state carries every field for every kind so the user can flip
+ * between kinds without losing input. We clean it to the discriminated-
+ * union shape before saving.
+ */
+interface DraftProject {
+  name: string;
+  description: string;
+  status: 'active' | 'beta' | 'planned' | 'deprecated';
+  icon?: string;
+  group?: string;
+  tags?: string[];
+  repo?: string;
+  sourceKind: HubProjectSource['kind'];
+  gitRepo: string;
+  gitRef: string;
+  gitPath: string;
+  urlUrl: string;
+  inlineMarkdown: string;
+  placementKind: HubProjectPlacement['kind'];
+  cardHref: string;
+  tabSections: 'all' | 'public';
+  nestedInto: string;
+  nestedDocsPath: string;
+  nestedGroup: string;
+}
+
+function emptyDraft(): DraftProject {
   return {
     name: '',
     description: '',
-    mode: 'link',
     status: 'active',
     icon: '',
     group: '',
-    href: '',
     tags: [],
-    git: { repo: '', ref: '' },
-    embedSections: 'all',
-    injectInto: '',
-    docsPath: 'docs',
+    repo: '',
+    sourceKind: 'none',
+    gitRepo: '',
+    gitRef: 'main',
+    gitPath: 'docs/public',
+    urlUrl: '',
+    inlineMarkdown: '',
+    placementKind: 'card',
+    cardHref: '',
+    tabSections: 'public',
+    nestedInto: '',
+    nestedDocsPath: 'docs',
+    nestedGroup: '',
+  };
+}
+
+function projectToDraft(p: HubProject): DraftProject {
+  const d = emptyDraft();
+  d.name = p.name;
+  d.description = p.description;
+  d.status = p.status ?? 'active';
+  d.icon = p.icon ?? '';
+  d.group = p.group ?? '';
+  d.tags = p.tags ? [...p.tags] : [];
+  d.repo = p.repo ?? '';
+
+  d.sourceKind = p.source.kind;
+  if (p.source.kind === 'git') {
+    d.gitRepo = p.source.repo;
+    d.gitRef = p.source.ref ?? 'main';
+    d.gitPath = p.source.path ?? 'docs/public';
+  } else if (p.source.kind === 'url') {
+    d.urlUrl = p.source.url;
+  } else if (p.source.kind === 'inline') {
+    d.inlineMarkdown = p.source.markdown;
+  }
+
+  d.placementKind = p.placement.kind;
+  if (p.placement.kind === 'card') {
+    d.cardHref = p.placement.href;
+  } else if (p.placement.kind === 'tab') {
+    const s = p.placement.sections;
+    d.tabSections = s === 'all' ? 'all' : 'public';
+  } else if (p.placement.kind === 'nested') {
+    d.nestedInto = p.placement.into;
+    d.nestedDocsPath = p.placement.docsPath ?? 'docs';
+    d.nestedGroup = p.placement.group ?? '';
+  }
+  return d;
+}
+
+function draftToProject(d: DraftProject): HubProject {
+  let source: HubProjectSource;
+  if (d.sourceKind === 'git') {
+    const g: Extract<HubProjectSource, { kind: 'git' }> = {
+      kind: 'git',
+      repo: d.gitRepo,
+    };
+    if (d.gitRef && d.gitRef !== 'main') g.ref = d.gitRef;
+    if (d.gitPath) g.path = d.gitPath;
+    source = g;
+  } else if (d.sourceKind === 'url') {
+    source = { kind: 'url', url: d.urlUrl };
+  } else if (d.sourceKind === 'inline') {
+    source = { kind: 'inline', markdown: d.inlineMarkdown };
+  } else {
+    source = { kind: 'none' };
+  }
+
+  let placement: HubProjectPlacement;
+  if (d.placementKind === 'tab') {
+    const t: Extract<HubProjectPlacement, { kind: 'tab' }> = { kind: 'tab' };
+    if (d.tabSections && d.tabSections !== 'public') t.sections = d.tabSections;
+    placement = t;
+  } else if (d.placementKind === 'nested') {
+    const n: Extract<HubProjectPlacement, { kind: 'nested' }> = {
+      kind: 'nested',
+      into: d.nestedInto,
+    };
+    if (d.nestedDocsPath && d.nestedDocsPath !== 'docs') n.docsPath = d.nestedDocsPath;
+    if (d.nestedGroup) n.group = d.nestedGroup;
+    placement = n;
+  } else {
+    placement = { kind: 'card', href: d.cardHref };
+  }
+
+  const project: HubProject = {
+    name: d.name.trim(),
+    description: d.description.trim(),
+    source,
+    placement,
   };
+  if (d.status && d.status !== 'active') project.status = d.status;
+  if (d.icon) project.icon = d.icon;
+  if (d.group) project.group = d.group;
+  if (d.tags && d.tags.length > 0) project.tags = d.tags;
+  if (d.repo) project.repo = d.repo;
+  return project;
 }
 
 /* ------------------------------------------------------------------ */
@@ -70,144 +188,138 @@ const primaryBtnStyle: React.CSSProperties = {
 };
 
 /* ------------------------------------------------------------------ */
-/*  Clean project for saving                                           */
+/*  Summary of the source+placement combo for the list view            */
 /* ------------------------------------------------------------------ */
-function cleanProject(draft: HubProject, original?: HubProject): HubProject {
-  const cleaned: HubProject = { ...draft };
-  const mode = cleaned.mode ?? 'link';
-  if (mode === 'link') {
-    delete cleaned.git;
-    delete cleaned.embedSections;
-    delete cleaned.injectInto;
-    delete cleaned.docsPath;
-    // Don't add mode: 'link' if original didn't have it (it's the default)
-    if (!original?.mode) delete cleaned.mode;
-  } else if (mode === 'embed') {
-    delete cleaned.href;
-    delete cleaned.injectInto;
-    delete cleaned.docsPath;
-  } else if (mode === 'inject') {
-    delete cleaned.href;
-    delete cleaned.embedSections;
-  }
-  if (!cleaned.icon) delete cleaned.icon;
-  if (!cleaned.group) delete cleaned.group;
-  if (!cleaned.href) delete cleaned.href;
-  if (cleaned.tags && cleaned.tags.length === 0) delete cleaned.tags;
-  if (cleaned.git && !cleaned.git.repo) delete cleaned.git;
-  if (cleaned.git && !cleaned.git.ref) delete cleaned.git.ref;
-  if (cleaned.status === 'active' && !original?.status) delete cleaned.status;
-
-  // Preserve original field ordering: rebuild using original's key order first
-  if (original) {
-    const ordered: any = {};
-    for (const key of Object.keys(original)) {
-      if (key in cleaned) ordered[key] = (cleaned as any)[key];
-    }
-    for (const key of Object.keys(cleaned)) {
-      if (!(key in ordered)) ordered[key] = (cleaned as any)[key];
-    }
-    return ordered as HubProject;
-  }
-  return cleaned;
+function combo(project: HubProject): string {
+  return `${project.source.kind} + ${project.placement.kind}`;
 }
 
 /* ------------------------------------------------------------------ */
 /*  Project form                                                       */
 /* ------------------------------------------------------------------ */
 function ProjectForm({
-  project,
+  draft,
   onChange,
   onSave,
   saving,
 }: {
-  project: HubProject;
-  onChange: (p: HubProject) => void;
+  draft: DraftProject;
+  onChange: (d: DraftProject) => void;
   onSave: () => void;
   saving: boolean;
 }) {
-  const mode = project.mode ?? 'link';
-
-  const set = <K extends keyof HubProject>(key: K, value: HubProject[K]) =>
-    onChange({ ...project, [key]: value });
+  const set = <K extends keyof DraftProject>(key: K, value: DraftProject[K]) =>
+    onChange({ ...draft, [key]: value });
 
   return (
     <div style={{ display: 'flex', flexDirection: 'column', gap: '0.875rem' }}>
       <div>
         <label style={labelStyle}>Name *</label>
-        <input style={inputStyle} value={project.name} onChange={(e) => set('name', e.target.value)} placeholder="my-project" />
+        <input style={inputStyle} value={draft.name} onChange={(e) => set('name', e.target.value)} placeholder="my-project" />
       </div>
       <div>
         <label style={labelStyle}>Description *</label>
-        <textarea style={{ ...inputStyle, minHeight: 72, resize: 'vertical' }} value={project.description} onChange={(e) => set('description', e.target.value)} placeholder="A short project description" />
+        <textarea style={{ ...inputStyle, minHeight: 72, resize: 'vertical' }} value={draft.description} onChange={(e) => set('description', e.target.value)} placeholder="A short project description" />
       </div>
       <div>
         <label style={labelStyle}>Icon</label>
-        <input style={inputStyle} value={project.icon ?? ''} onChange={(e) => set('icon', e.target.value)} placeholder="e.g. book, code, rocket" />
+        <input style={inputStyle} value={draft.icon ?? ''} onChange={(e) => set('icon', e.target.value)} placeholder="e.g. book, code, rocket" />
       </div>
       <div style={{ display: 'flex', gap: '0.75rem' }}>
-        <div style={{ flex: 1 }}>
-          <label style={labelStyle}>Mode</label>
-          <select style={inputStyle} value={mode} onChange={(e) => set('mode', e.target.value as HubProject['mode'])}>
-            <option value="link">Link</option>
-            <option value="embed">Embed</option>
-            <option value="inject">Inject</option>
-          </select>
-        </div>
         <div style={{ flex: 1 }}>
           <label style={labelStyle}>Status</label>
-          <select style={inputStyle} value={project.status ?? 'active'} onChange={(e) => set('status', e.target.value as HubProject['status'])}>
+          <select style={inputStyle} value={draft.status} onChange={(e) => set('status', e.target.value as DraftProject['status'])}>
             <option value="active">Active</option>
             <option value="beta">Beta</option>
             <option value="planned">Planned</option>
             <option value="deprecated">Deprecated</option>
           </select>
         </div>
-      </div>
-      <div>
-        <label style={labelStyle}>Group</label>
-        <input style={inputStyle} value={project.group ?? ''} onChange={(e) => set('group', e.target.value)} placeholder="e.g. backend, frontend" />
+        <div style={{ flex: 1 }}>
+          <label style={labelStyle}>Group</label>
+          <input style={inputStyle} value={draft.group ?? ''} onChange={(e) => set('group', e.target.value)} placeholder="e.g. backend, frontend" />
+        </div>
       </div>
 
-      {mode === 'link' && (
-        <div>
-          <label style={labelStyle}>URL (href)</label>
-          <input style={inputStyle} value={project.href ?? ''} onChange={(e) => set('href', e.target.value)} placeholder="https://example.com/docs" />
+      <div style={{ display: 'flex', gap: '0.75rem' }}>
+        <div style={{ flex: 1 }}>
+          <label style={labelStyle}>Source</label>
+          <select
+            style={inputStyle}
+            value={draft.sourceKind}
+            onChange={(e) => set('sourceKind', e.target.value as HubProjectSource['kind'])}
+          >
+            <option value="none">none (no content pulled)</option>
+            <option value="git">git (sparse clone)</option>
+            <option value="url" disabled>url (reserved)</option>
+            <option value="inline" disabled>inline (reserved)</option>
+          </select>
         </div>
-      )}
+        <div style={{ flex: 1 }}>
+          <label style={labelStyle}>Placement</label>
+          <select
+            style={inputStyle}
+            value={draft.placementKind}
+            onChange={(e) => set('placementKind', e.target.value as HubProjectPlacement['kind'])}
+          >
+            <option value="card">card (grid entry, link out)</option>
+            <option value="tab">tab (full hub tab)</option>
+            <option value="nested">nested (into existing section)</option>
+          </select>
+        </div>
+      </div>
 
-      {(mode === 'embed' || mode === 'inject') && (
+      {draft.sourceKind === 'git' && (
         <>
           <div>
-            <label style={labelStyle}>Git Repo</label>
-            <input style={inputStyle} value={project.git?.repo ?? ''} onChange={(e) => set('git', { ...project.git, repo: e.target.value })} placeholder="org/repo" />
+            <label style={labelStyle}>Git repo *</label>
+            <input style={inputStyle} value={draft.gitRepo} onChange={(e) => set('gitRepo', e.target.value)} placeholder="https://github.com/org/repo.git" />
           </div>
-          <div>
-            <label style={labelStyle}>Git Ref</label>
-            <input style={inputStyle} value={project.git?.ref ?? ''} onChange={(e) => set('git', { ...project.git, repo: project.git?.repo ?? '', ref: e.target.value })} placeholder="main" />
+          <div style={{ display: 'flex', gap: '0.75rem' }}>
+            <div style={{ flex: 1 }}>
+              <label style={labelStyle}>Git ref</label>
+              <input style={inputStyle} value={draft.gitRef} onChange={(e) => set('gitRef', e.target.value)} placeholder="main" />
+            </div>
+            <div style={{ flex: 1 }}>
+              <label style={labelStyle}>Git path</label>
+              <input style={inputStyle} value={draft.gitPath} onChange={(e) => set('gitPath', e.target.value)} placeholder="docs/public" />
+            </div>
           </div>
         </>
       )}
 
-      {mode === 'embed' && (
+      {draft.placementKind === 'card' && (
         <div>
-          <label style={labelStyle}>Embed Sections</label>
-          <select style={inputStyle} value={typeof project.embedSections === 'string' ? project.embedSections : 'all'} onChange={(e) => set('embedSections', e.target.value as 'all' | 'public')}>
-            <option value="all">All</option>
-            <option value="public">Public</option>
+          <label style={labelStyle}>Card href *</label>
+          <input style={inputStyle} value={draft.cardHref} onChange={(e) => set('cardHref', e.target.value)} placeholder="https://example.com/docs" />
+        </div>
+      )}
+
+      {draft.placementKind === 'tab' && (
+        <div>
+          <label style={labelStyle}>Tab sections</label>
+          <select style={inputStyle} value={draft.tabSections} onChange={(e) => set('tabSections', e.target.value as 'all' | 'public')}>
+            <option value="public">public (non-draft)</option>
+            <option value="all">all</option>
           </select>
         </div>
       )}
 
-      {mode === 'inject' && (
+      {draft.placementKind === 'nested' && (
         <>
           <div>
-            <label style={labelStyle}>Inject Into</label>
-            <input style={inputStyle} value={project.injectInto ?? ''} onChange={(e) => set('injectInto', e.target.value)} placeholder="section-id" />
+            <label style={labelStyle}>Nest into (section label) *</label>
+            <input style={inputStyle} value={draft.nestedInto} onChange={(e) => set('nestedInto', e.target.value)} placeholder="Documentation" />
           </div>
-          <div>
-            <label style={labelStyle}>Docs Path</label>
-            <input style={inputStyle} value={project.docsPath ?? 'docs'} onChange={(e) => set('docsPath', e.target.value)} placeholder="docs" />
+          <div style={{ display: 'flex', gap: '0.75rem' }}>
+            <div style={{ flex: 1 }}>
+              <label style={labelStyle}>Docs path (in cloned repo)</label>
+              <input style={inputStyle} value={draft.nestedDocsPath} onChange={(e) => set('nestedDocsPath', e.target.value)} placeholder="docs" />
+            </div>
+            <div style={{ flex: 1 }}>
+              <label style={labelStyle}>Nested group (optional)</label>
+              <input style={inputStyle} value={draft.nestedGroup} onChange={(e) => set('nestedGroup', e.target.value)} placeholder="Services" />
+            </div>
           </div>
         </>
       )}
@@ -216,7 +328,7 @@ function ProjectForm({
         <label style={labelStyle}>Tags (comma-separated)</label>
         <input
           style={inputStyle}
-          value={(project.tags ?? []).join(', ')}
+          value={(draft.tags ?? []).join(', ')}
           onChange={(e) => set('tags', e.target.value.split(',').map((t) => t.trim()).filter(Boolean))}
           placeholder="api, docs, internal"
         />
@@ -224,7 +336,7 @@ function ProjectForm({
 
       <div style={{ display: 'flex', justifyContent: 'flex-end', marginTop: '0.25rem' }}>
         <button style={primaryBtnStyle} onClick={onSave} disabled={saving}>
-          {saving ? 'Saving\u2026' : 'Save Project'}
+          {saving ? 'Saving...' : 'Save Project'}
         </button>
       </div>
     </div>
@@ -243,7 +355,7 @@ export function ProjectsManager() {
 
   // modal state
   const [editIndex, setEditIndex] = useState<number | null>(null); // null = closed, -1 = new
-  const [draft, setDraft] = useState<HubProject>(emptyProject());
+  const [draft, setDraft] = useState<DraftProject>(emptyDraft());
   const [saving, setSaving] = useState(false);
 
   // delete confirm
@@ -318,9 +430,20 @@ export function ProjectsManager() {
       show('Name and description are required', 'error');
       return;
     }
+    if (draft.sourceKind === 'git' && !draft.gitRepo.trim()) {
+      show('Git repo is required for git source', 'error');
+      return;
+    }
+    if (draft.placementKind === 'card' && !draft.cardHref.trim()) {
+      show('Card href is required for card placement', 'error');
+      return;
+    }
+    if (draft.placementKind === 'nested' && !draft.nestedInto.trim()) {
+      show('Nest-into section label is required for nested placement', 'error');
+      return;
+    }
 
-    const original = editIndex !== null && editIndex >= 0 ? projects[editIndex] : undefined;
-    const cleaned = cleanProject(draft, original);
+    const cleaned = draftToProject(draft);
     const next = [...projects];
     if (editIndex === -1) {
       next.push(cleaned);
@@ -360,18 +483,13 @@ export function ProjectsManager() {
 
   /* ---------- open modal ---------- */
   const openAdd = () => {
-    setDraft(emptyProject());
+    setDraft(emptyDraft());
     setEditIndex(-1);
   };
 
   const openEdit = (index: number) => {
     const p = projects[index];
-    setDraft({
-      ...emptyProject(),
-      ...p,
-      git: p.git ? { ...p.git } : { repo: '', ref: '' },
-      tags: p.tags ? [...p.tags] : [],
-    });
+    setDraft(projectToDraft(p));
     setEditIndex(index);
   };
 
@@ -415,7 +533,7 @@ export function ProjectsManager() {
           <table style={{ width: '100%', borderCollapse: 'collapse', fontSize: '0.875rem' }}>
             <thead>
               <tr style={{ backgroundColor: 'var(--clearify-bg-secondary)', borderBottom: '1px solid var(--clearify-border)' }}>
-                {['Name', 'Description', 'Mode', 'Group', 'Status', ''].map((h) => (
+                {['Name', 'Description', 'Source + Placement', 'Group', 'Status', ''].map((h) => (
                   <th key={h} style={{ textAlign: 'left', padding: '0.625rem 0.75rem', fontWeight: 600, color: 'var(--clearify-text-secondary)', fontSize: '0.8125rem' }}>{h}</th>
                 ))}
               </tr>
@@ -438,8 +556,8 @@ export function ProjectsManager() {
                     <td style={{ padding: '0.625rem 0.75rem', color: 'var(--clearify-text-secondary)', maxWidth: 250, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
                       {p.description}
                     </td>
-                    <td style={{ padding: '0.625rem 0.75rem', color: 'var(--clearify-text-secondary)' }}>{p.mode ?? 'link'}</td>
-                    <td style={{ padding: '0.625rem 0.75rem', color: 'var(--clearify-text-secondary)' }}>{p.group ?? '\u2014'}</td>
+                    <td style={{ padding: '0.625rem 0.75rem', color: 'var(--clearify-text-secondary)' }}>{combo(p)}</td>
+                    <td style={{ padding: '0.625rem 0.75rem', color: 'var(--clearify-text-secondary)' }}>{p.group ?? '-'}</td>
                     <td style={{ padding: '0.625rem 0.75rem' }}>
                       <span style={{ display: 'inline-block', padding: '0.125rem 0.5rem', borderRadius: '9999px', fontSize: '0.75rem', fontWeight: 600, backgroundColor: colors.bg, color: colors.text }}>
                         {st}
@@ -512,7 +630,7 @@ export function ProjectsManager() {
 
       {/* Edit / Add modal */}
       <Modal open={editIndex !== null} onClose={() => setEditIndex(null)} title={editIndex === -1 ? 'Add Project' : `Edit: ${editIndex !== null && editIndex >= 0 ? projects[editIndex]?.name ?? '' : ''}`}>
-        <ProjectForm project={draft} onChange={setDraft} onSave={handleSave} saving={saving} />
+        <ProjectForm draft={draft} onChange={setDraft} onSave={handleSave} saving={saving} />
       </Modal>
 
       {/* Delete confirmation */}

package/src/theme/components/ProjectGrid.tsx

@@ -8,6 +8,22 @@ interface ProjectGridProps {
   children?: React.ReactNode;
 }
 
+function projectHref(project: HubProject): string | undefined {
+  if (project.placement.kind === 'card') return project.placement.href;
+  if (project.placement.kind === 'tab') {
+    // Default to the project's own tab path on the hub
+    const slug = project.name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-|-$/g, '');
+    return `/${slug}`;
+  }
+  if (project.placement.kind === 'nested') {
+    return `/${project.placement.into}`;
+  }
+  return undefined;
+}
+
 function ProjectGridInner({ cols, projects }: { cols: number; projects: HubProject[] }) {
   return (
     <div
@@ -23,7 +39,7 @@ function ProjectGridInner({ cols, projects }: { cols: number; projects: HubProje
           key={project.name}
           name={project.name}
           description={project.description}
-          href={project.href}
+          href={projectHref(project)}
           repo={project.repo}
           status={project.status}
           icon={project.icon}