@marlinjai/clearify 1.19.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-HVHCUAVU.js → chunk-GPBEDIOY.js}

@@ -282,7 +282,7 @@ ${hasInternal ? `
 `);
   const secretMode = options.secretMode ?? "prompt";
   if (options.hub) {
-    const { registerWithHub } = await import("./hub-register-M7C3G3FE.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-M7C3G3FE.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-M7C3G3FE.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;
@@ -310,9 +312,15 @@ jobs:
 }
 async function registerWithHub(options) {
   const clientId = process.env.CLEARIFY_GITHUB_CLIENT_ID;
-  if (!clientId) {
-    console.error("\n  Error: CLEARIFY_GITHUB_CLIENT_ID environment variable is not set.");
-    console.error("  Set it to your GitHub OAuth App client ID and try again.\n");
+  if (!clientId && !options.hubToken) {
+    console.error("\n  Error: no GitHub credentials available for hub onboarding.");
+    console.error("  Clearify needs one of these to write the hub registry entry:\n");
+    console.error("    1) Set CLEARIFY_GITHUB_CLIENT_ID to a GitHub OAuth App client ID");
+    console.error("       (create one at https://github.com/settings/applications/new,");
+    console.error('       scope "repo"), then re-run this command.');
+    console.error("    2) Pass --hub-token <pat> to use a Personal Access Token directly");
+    console.error('       (fine-grained PAT with "Contents: Read and Write" on the hub repo).');
+    console.error("");
     process.exit(1);
   }
   const projectName = options.projectName ?? detectProjectName();
@@ -328,8 +336,14 @@ async function registerWithHub(options) {
   const hub = await promptHubRepo();
   console.log(`  Hub: ${hub.owner}/${hub.repo}
 `);
-  console.log("  Starting GitHub authentication...");
-  const token = await githubDeviceAuth(clientId);
+  let token;
+  if (options.hubToken) {
+    console.log("  Using provided --hub-token for GitHub API calls.");
+    token = options.hubToken;
+  } else {
+    console.log("  Starting GitHub authentication...");
+    token = await githubDeviceAuth(clientId);
+  }
   console.log("  Updating hub registry...");
   await updateHubRegistry(token, hub, {
     name: projectName,
@@ -384,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-HVHCUAVU.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-HVHCUAVU.js";
+} from "../chunk-GPBEDIOY.js";
 export {
   init
 };