@knitli/astro-docs-template 0.1.2 → 0.2.1

package/{dist/index.js → src/index.ts}

@@ -1,46 +1,89 @@
-import { existsSync, statSync, mkdirSync, readdirSync, readFileSync, writeFileSync, cpSync } from 'node:fs';
-import { dirname, resolve, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-export { default as createConfig } from './config.js';
-
-const __dirname$1 = dirname(fileURLToPath(import.meta.url));
-const SCAFFOLDING_DIR = resolve(__dirname$1, "../scaffolding");
-const PIECES = {
+// SPDX-FileCopyrightText: 2026 Knitli Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export { type DocsTemplateOptions, default as createConfig } from "./config.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCAFFOLDING_DIR = resolve(__dirname, "../scaffolding");
+
+// ── Options ──
+
+export interface InitOptions {
+  /** Display name for the product (e.g. "Recoco", "CodeWeaver") */
+  appName: string;
+  /** npm package name (e.g. "@knitli-site/recoco-docs") */
+  name: string;
+  /** Short product description */
+  description: string;
+  /** Cloudflare Worker name (e.g. "recoco-docs") */
+  workerName?: string;
+  /** Whether this is a CodeWeaver-branded site */
+  is_codeweaver?: boolean;
+}
+
+export interface AddPiecesOptions extends InitOptions {
+  pieces: PieceName[];
+  /** Overwrite existing files (default: false — skips with a warning) */
+  force?: boolean;
+}
+
+// ── Piece definitions ──
+
+export const PIECES = {
   config: {
     description: "Astro config using createConfig()",
-    paths: ["astro.config.ts"]
+    paths: ["astro.config.ts"],
   },
   wrangler: {
     description: "Cloudflare Worker deployment config",
-    paths: ["wrangler.jsonc"]
+    paths: ["wrangler.jsonc"],
   },
   tsconfig: {
     description: "TypeScript config extending shared base",
-    paths: ["tsconfig.json"]
+    paths: ["tsconfig.json"],
   },
   content: {
     description: "Content collections, env types, and tags",
-    paths: ["src/content.config.ts", "src/env.d.ts", "tags.yml"]
+    paths: ["src/content.config.ts", "src/env.d.ts", "tags.yml"],
   },
   mise: {
     description: "mise dev tasks (build, deploy, clean, etc.)",
-    paths: ["mise.toml"]
+    paths: ["mise.toml"],
   },
   styles: {
     description: "Custom CSS hook for site-specific styles",
-    paths: ["src/styles/custom.css"]
+    paths: ["src/styles/custom.css"],
   },
   deps: {
     description: "package.json with template dependencies",
-    paths: ["package.json"]
+    paths: ["package.json"],
   },
   "starter-content": {
     description: "Example documentation pages",
-    paths: ["src/content/docs"]
-  }
-};
-const PIECE_NAMES = Object.keys(PIECES);
-const TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
+    paths: ["src/content/docs"],
+  },
+} as const;
+
+export type PieceName = keyof typeof PIECES;
+export const PIECE_NAMES = Object.keys(PIECES) as PieceName[];
+
+// ── Shared helpers ──
+
+/** File extensions that should have placeholder substitution applied */
+const TEXT_EXTENSIONS = new Set([
   ".ts",
   ".js",
   ".mjs",
@@ -53,28 +96,42 @@ const TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
   ".css",
   ".html",
   ".astro",
-  ".toml"
+  ".toml",
 ]);
-function isTextFile(filePath) {
+
+function isTextFile(filePath: string): boolean {
   return TEXT_EXTENSIONS.has(filePath.slice(filePath.lastIndexOf(".")));
 }
-function buildReplacements(options) {
+
+function buildReplacements(options: InitOptions): Record<string, string> {
   return {
     "{{appName}}": options.appName,
     "{{appNameLower}}": options.appName.toLowerCase(),
     "{{name}}": options.name,
     "{{description}}": options.description,
-    "{{workerName}}": options.workerName ?? `${options.appName.toLowerCase()}-docs`
+    "{{workerName}}":
+      options.workerName ?? `${options.appName.toLowerCase()}-docs`,
   };
 }
-function applyReplacements(content, replacements) {
+
+function applyReplacements(
+  content: string,
+  replacements: Record<string, string>,
+): string {
   let result = content;
   for (const [placeholder, value] of Object.entries(replacements)) {
     result = result.replaceAll(placeholder, value);
   }
   return result;
 }
-function copyFile(srcPath, destPath, replacements, created, force) {
+
+function copyFile(
+  srcPath: string,
+  destPath: string,
+  replacements: Record<string, string>,
+  created: string[],
+  force?: boolean,
+): void {
   if (!force && existsSync(destPath)) {
     console.log(`  skip ${destPath} (exists, use --force to overwrite)`);
     return;
@@ -88,7 +145,14 @@ function copyFile(srcPath, destPath, replacements, created, force) {
   }
   created.push(destPath);
 }
-function copyDirRecursive(srcDir, destDir, replacements, created, force) {
+
+function copyDirRecursive(
+  srcDir: string,
+  destDir: string,
+  replacements: Record<string, string>,
+  created: string[],
+  force?: boolean,
+): void {
   mkdirSync(destDir, { recursive: true });
   for (const entry of readdirSync(srcDir)) {
     const srcPath = join(srcDir, entry);
@@ -100,51 +164,79 @@ function copyDirRecursive(srcDir, destDir, replacements, created, force) {
     }
   }
 }
-function initDocsTemplate(targetPath, options) {
+
+// ── Public API ──
+
+/**
+ * Initialize a new Knitli docs site from the template scaffolding.
+ *
+ * Copies all files from the scaffolding directory to the target path,
+ * applying placeholder substitution to text files.
+ */
+export function initDocsTemplate(
+  targetPath: string,
+  options: InitOptions,
+): string[] {
   const target = resolve(targetPath);
   const replacements = buildReplacements(options);
-  const created = [];
+  const created: string[] = [];
+
   if (!existsSync(SCAFFOLDING_DIR)) {
     throw new Error(`Scaffolding directory not found at ${SCAFFOLDING_DIR}`);
   }
+
   copyDirRecursive(SCAFFOLDING_DIR, target, replacements, created, true);
   return created;
 }
-function addPieces(targetPath, options) {
+
+/**
+ * Add specific pieces from the template scaffolding to an existing project.
+ *
+ * Unlike initDocsTemplate, this only copies the files belonging to the
+ * requested pieces and skips existing files unless force is set.
+ */
+export function addPieces(
+  targetPath: string,
+  options: AddPiecesOptions,
+): string[] {
   const target = resolve(targetPath);
   const replacements = buildReplacements(options);
-  const created = [];
+  const created: string[] = [];
+
   if (!existsSync(SCAFFOLDING_DIR)) {
     throw new Error(`Scaffolding directory not found at ${SCAFFOLDING_DIR}`);
   }
+
   for (const piece of options.pieces) {
     const pieceDef = PIECES[piece];
     if (!pieceDef) {
       throw new Error(
-        `Unknown piece: ${piece}. Available: ${PIECE_NAMES.join(", ")}`
+        `Unknown piece: ${piece}. Available: ${PIECE_NAMES.join(", ")}`,
       );
     }
+
     for (const relPath of pieceDef.paths) {
       const srcPath = join(SCAFFOLDING_DIR, relPath);
       const destPath = join(target, relPath);
+
       if (!existsSync(srcPath)) {
         console.warn(`  warn: ${relPath} not found in scaffolding, skipping`);
         continue;
       }
+
       if (statSync(srcPath).isDirectory()) {
         copyDirRecursive(
           srcPath,
           destPath,
           replacements,
           created,
-          options.force
+          options.force,
         );
       } else {
         copyFile(srcPath, destPath, replacements, created, options.force);
       }
     }
   }
+
   return created;
 }
-
-export { PIECES, PIECE_NAMES, addPieces, initDocsTemplate };

package/dist/cli.d.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env bun
-export {};
-//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/config.d.ts

@@ -1,59 +0,0 @@
-import type { OutgoingHttpHeaders } from "node:http2";
-type defaultIntegration = "sitemap" | "astroD2" | "markdoc" | "mdx" | "favicons" | "cloudflare-pages-headers";
-export declare const headlineLogoDark: string, headlineLogoLight: string, variables: string, docsStyle: string, faviconIco: string, faviconSvg: string;
-declare const shikiCfg: {
-    themes: {
-        light: "catppuccin-latte";
-        dark: "catppuccin-mocha";
-    };
-    bundledLangs: string[];
-    langAlias: {
-        js: string;
-        md: string;
-        py: string;
-        rs: string;
-        sh: string;
-        yml: string;
-    };
-};
-declare const imgDomains: {
-    protocol: string;
-    hostname: string;
-}[];
-export interface DocsTemplateOptions {
-    appName: string;
-    description: string;
-    llmConfig: {
-        llmDescription: string;
-        promotePatterns: string[];
-        demotePatterns: string[];
-    };
-    rootDir: string;
-    shikiConfig?: typeof shikiCfg;
-    logoDark?: string;
-    logoLight?: string;
-    imageDomains?: typeof imgDomains;
-    is_codeweaver?: boolean;
-    sitemapFilter?: (page: string) => boolean;
-    linkValidationConfig?: Record<string, unknown>;
-    sidebarConfig?: {
-        label: string;
-        autogenerate: {
-            directory: string;
-        };
-    }[];
-    unwantedPlugins?: string[];
-    pluginConfigs?: Record<string, any>;
-    unwantedIntegrations?: defaultIntegration[];
-    integrationConfigs?: Record<string, any>;
-    headersConfig?: OutgoingHttpHeaders;
-}
-export type IntegrationOptions = Pick<DocsTemplateOptions, "appName" | "sitemapFilter" | "integrationConfigs"> & {
-    unwantedIntegrations?: defaultIntegration[];
-};
-export type PluginOptions = Pick<DocsTemplateOptions, "appName" | "llmConfig" | "pluginConfigs"> & {
-    unwantedPlugins?: string[];
-};
-export default function createConfig(options: DocsTemplateOptions): import("astro").AstroUserConfig<never, never, never>;
-export {};
-//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AA6BtD,KAAK,kBAAkB,GACnB,SAAS,GACT,SAAS,GACT,SAAS,GACT,KAAK,GACL,UAAU,GACV,0BAA0B,CAAC;AAQ/B,eAAO,MACL,gBAAgB,UAChB,iBAAiB,UACjB,SAAS,UACT,SAAS,UACT,UAAU,UACV,UAAU,QACE,CAAC;AAEf,QAAA,MAAM,QAAQ;;;;;;;;;;;;;;CAyBb,CAAC;AAEF,QAAA,MAAM,UAAU;;;GAMf,CAAC;AA8DF,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE;QACT,cAAc,EAAE,MAAM,CAAC;QACvB,eAAe,EAAE,MAAM,EAAE,CAAC;QAC1B,cAAc,EAAE,MAAM,EAAE,CAAC;KAC1B,CAAC;IACF,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,QAAQ,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,UAAU,CAAC;IACjC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAC1C,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/C,aAAa,CAAC,EAAE;QACd,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE;YAAE,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC;KACrC,EAAE,CAAC;IACJ,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAE3B,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACpC,oBAAoB,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAE5C,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACzC,aAAa,CAAC,EAAE,mBAAmB,CAAC;CACrC;AAED,MAAM,MAAM,kBAAkB,GAAG,IAAI,CACnC,mBAAmB,EACnB,SAAS,GAAG,eAAe,GAAG,oBAAoB,CACnD,GAAG;IAAE,oBAAoB,CAAC,EAAE,kBAAkB,EAAE,CAAA;CAAE,CAAC;AA+DpD,MAAM,MAAM,aAAa,GAAG,IAAI,CAC9B,mBAAmB,EACnB,SAAS,GAAG,WAAW,GAAG,eAAe,CAC1C,GAAG;IAAE,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAoEnC,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,OAAO,EAAE,mBAAmB,wDAuOhE"}

package/dist/index.d.ts

@@ -1,69 +0,0 @@
-export { type DocsTemplateOptions, default as createConfig } from "./config.js";
-export interface InitOptions {
-    /** Display name for the product (e.g. "Recoco", "CodeWeaver") */
-    appName: string;
-    /** npm package name (e.g. "@knitli-site/recoco-docs") */
-    name: string;
-    /** Short product description */
-    description: string;
-    /** Cloudflare Worker name (e.g. "recoco-docs") */
-    workerName?: string;
-    /** Whether this is a CodeWeaver-branded site */
-    is_codeweaver?: boolean;
-}
-export interface AddPiecesOptions extends InitOptions {
-    pieces: PieceName[];
-    /** Overwrite existing files (default: false — skips with a warning) */
-    force?: boolean;
-}
-export declare const PIECES: {
-    readonly config: {
-        readonly description: "Astro config using createConfig()";
-        readonly paths: readonly ["astro.config.ts"];
-    };
-    readonly wrangler: {
-        readonly description: "Cloudflare Worker deployment config";
-        readonly paths: readonly ["wrangler.jsonc"];
-    };
-    readonly tsconfig: {
-        readonly description: "TypeScript config extending shared base";
-        readonly paths: readonly ["tsconfig.json"];
-    };
-    readonly content: {
-        readonly description: "Content collections, env types, and tags";
-        readonly paths: readonly ["src/content.config.ts", "src/env.d.ts", "tags.yml"];
-    };
-    readonly mise: {
-        readonly description: "mise dev tasks (build, deploy, clean, etc.)";
-        readonly paths: readonly ["mise.toml"];
-    };
-    readonly styles: {
-        readonly description: "Custom CSS hook for site-specific styles";
-        readonly paths: readonly ["src/styles/custom.css"];
-    };
-    readonly deps: {
-        readonly description: "package.json with template dependencies";
-        readonly paths: readonly ["package.json"];
-    };
-    readonly "starter-content": {
-        readonly description: "Example documentation pages";
-        readonly paths: readonly ["src/content/docs"];
-    };
-};
-export type PieceName = keyof typeof PIECES;
-export declare const PIECE_NAMES: PieceName[];
-/**
- * Initialize a new Knitli docs site from the template scaffolding.
- *
- * Copies all files from the scaffolding directory to the target path,
- * applying placeholder substitution to text files.
- */
-export declare function initDocsTemplate(targetPath: string, options: InitOptions): string[];
-/**
- * Add specific pieces from the template scaffolding to an existing project.
- *
- * Unlike initDocsTemplate, this only copies the files belonging to the
- * requested pieces and skips existing files unless force is set.
- */
-export declare function addPieces(targetPath: string, options: AddPiecesOptions): string[];
-//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,KAAK,mBAAmB,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,aAAa,CAAC;AAOhF,MAAM,WAAW,WAAW;IAC1B,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAID,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiCT,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,MAAM,CAAC;AAC5C,eAAO,MAAM,WAAW,EAA0B,SAAS,EAAE,CAAC;AAyF9D;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,WAAW,GACnB,MAAM,EAAE,CAWV;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,gBAAgB,GACxB,MAAM,EAAE,CAyCV"}