@knitli/astro-docs-template 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knitli/astro-docs-template",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Opinionated Astro + Starlight docs site template with Knitli branding",
   "keywords": [
     "knitli",
@@ -22,6 +22,9 @@
     ".": "./src/index.ts",
     "./config": "./src/config.ts"
   },
+  "bin": {
+    "knitli-docs": "src/cli.ts"
+  },
   "files": [
     "src",
     "scaffolding",

package/scaffolding/package.json

@@ -4,11 +4,13 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "astro": "bunx astro",
+    "prebuild": "test -f ./node_modules/bun/install.js && node ./node_modules/bun/install.js; bunx wrangler types; bunx astro sync",
     "build": "bunx astro build",
-    "deploy": "bunx astro build && bunx wrangler deploy",
+    "deploy": "bun run build && bunx wrangler deploy",
     "dev": "bunx astro dev",
-    "generate-types": "bunx wrangler types",
-    "preview": "bunx astro build && bunx astro preview"
+    "preview": "bunx astro preview",
+    "wrangler": "bunx wrangler"
   },
   "dependencies": {
     "@knitli/astro-docs-template": "workspace:*",

package/src/cli.ts

@@ -0,0 +1,179 @@
+#!/usr/bin/env bun
+// SPDX-FileCopyrightText: 2026 Knitli Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import {
+  addPieces,
+  initDocsTemplate,
+  PIECES,
+  PIECE_NAMES,
+  type InitOptions,
+  type PieceName,
+} from "./index.js";
+
+// ── Arg parsing ──
+
+function parseArgs(argv: string[]) {
+  const flags: Record<string, string> = {};
+  const positional: string[] = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    if (arg === "--help" || arg === "-h") {
+      flags.help = "true";
+    } else if (arg === "--force" || arg === "-f") {
+      flags.force = "true";
+    } else if (arg.startsWith("--") && i + 1 < argv.length) {
+      flags[arg.slice(2)] = argv[++i]!;
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  return { flags, positional };
+}
+
+// ── Help text ──
+
+const HELP = `knitli-docs — scaffold and manage Knitli docs sites
+
+Usage:
+  knitli-docs init [dir]                  Full scaffold into dir (default: .)
+  knitli-docs add <piece...> [--dir d]    Add specific pieces to a project
+  knitli-docs list                        Show available pieces
+
+Pieces:
+${Object.entries(PIECES)
+  .map(([name, { description }]) => `  ${name.padEnd(18)} ${description}`)
+  .join("\n")}
+
+Options:
+  --app-name <name>       Product name (e.g. "Recoco")
+  --name <pkg>            npm package name (e.g. "@knitli-site/recoco-docs")
+  --description <desc>    Short product description
+  --worker-name <name>    Cloudflare Worker name (default: <appname>-docs)
+  --dir <path>            Target directory for 'add' (default: .)
+  --force, -f             Overwrite existing files
+  --help, -h              Show this help
+`;
+
+// ── Interactive prompts ──
+
+async function getOptions(
+  flags: Record<string, string>,
+): Promise<InitOptions> {
+  const rl = createInterface({ input: stdin, output: stdout });
+
+  const ask = async (
+    question: string,
+    defaultValue?: string,
+  ): Promise<string> => {
+    const suffix = defaultValue ? ` [${defaultValue}]` : "";
+    const answer = await rl.question(`${question}${suffix}: `);
+    return answer.trim() || defaultValue || "";
+  };
+
+  try {
+    const appName =
+      flags["app-name"] || (await ask("Product name (e.g. Recoco)"));
+    if (!appName) {
+      console.error("Error: product name is required");
+      process.exit(1);
+    }
+
+    const name =
+      flags.name ||
+      (await ask(
+        "npm package name",
+        `@knitli-site/${appName.toLowerCase()}-docs`,
+      ));
+    const description =
+      flags.description || (await ask("Short description"));
+    const workerName =
+      flags["worker-name"] ||
+      (await ask("Worker name", `${appName.toLowerCase()}-docs`));
+
+    return { appName, name, description, workerName };
+  } finally {
+    rl.close();
+  }
+}
+
+// ── Commands ──
+
+async function main() {
+  const { flags, positional } = parseArgs(process.argv.slice(2));
+  const command = positional[0];
+
+  if (flags.help || !command) {
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  switch (command) {
+    case "list": {
+      console.log("\nAvailable pieces:\n");
+      for (const [name, { description, paths }] of Object.entries(PIECES)) {
+        console.log(`  ${name.padEnd(18)} ${description}`);
+        for (const p of paths) {
+          console.log(`  ${"".padEnd(18)}   └ ${p}`);
+        }
+      }
+      console.log();
+      break;
+    }
+
+    case "init": {
+      const dir = flags.dir || positional[1] || ".";
+      const options = await getOptions(flags);
+      console.log(`\nScaffolding into ${dir} ...\n`);
+      const created = initDocsTemplate(dir, options);
+      console.log(`\nDone — ${created.length} files created`);
+      break;
+    }
+
+    case "add": {
+      const pieces = positional.slice(1).filter((p) => !p.startsWith("-"));
+      if (pieces.length === 0) {
+        console.error(
+          "Error: specify at least one piece. Run 'knitli-docs list' to see options.",
+        );
+        process.exit(1);
+      }
+
+      const invalid = pieces.filter(
+        (p) => !PIECE_NAMES.includes(p as PieceName),
+      );
+      if (invalid.length > 0) {
+        console.error(`Error: unknown piece(s): ${invalid.join(", ")}`);
+        console.error(`Available: ${PIECE_NAMES.join(", ")}`);
+        process.exit(1);
+      }
+
+      const dir = flags.dir || ".";
+      const options = await getOptions(flags);
+      console.log(`\nAdding ${pieces.join(", ")} to ${dir} ...\n`);
+      const created = addPieces(dir, {
+        ...options,
+        pieces: pieces as PieceName[],
+        force: flags.force === "true",
+      });
+      console.log(`\nDone — ${created.length} files created`);
+      break;
+    }
+
+    default: {
+      console.error(`Unknown command: ${command}\n`);
+      console.log(HELP);
+      process.exit(1);
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});

package/src/config.ts

@@ -372,7 +372,7 @@ export default function createConfig(options: DocsTemplateOptions) {
       ),
       rehypePlugins: [
         rehypeExternalLinks({
-          content: { type: "text", value: " 🔗" },
+          content: { type: "text", value: " ↗" },
           rel: ["nofollow"],
         }),
       ],

package/src/index.ts

@@ -19,6 +19,8 @@ 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;
@@ -32,6 +34,54 @@ export interface InitOptions {
   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"],
+  },
+  wrangler: {
+    description: "Cloudflare Worker deployment config",
+    paths: ["wrangler.jsonc"],
+  },
+  tsconfig: {
+    description: "TypeScript config extending shared base",
+    paths: ["tsconfig.json"],
+  },
+  content: {
+    description: "Content collections, env types, and tags",
+    paths: ["src/content.config.ts", "src/env.d.ts", "tags.yml"],
+  },
+  mise: {
+    description: "mise dev tasks (build, deploy, clean, etc.)",
+    paths: ["mise.toml"],
+  },
+  styles: {
+    description: "Custom CSS hook for site-specific styles",
+    paths: ["src/styles/custom.css"],
+  },
+  deps: {
+    description: "package.json with template dependencies",
+    paths: ["package.json"],
+  },
+  "starter-content": {
+    description: "Example documentation pages",
+    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",
@@ -46,7 +96,7 @@ const TEXT_EXTENSIONS = new Set([
   ".css",
   ".html",
   ".astro",
-  ".d.ts",
+  ".toml",
 ]);
 
 function isTextFile(filePath: string): boolean {
@@ -75,15 +125,53 @@ function applyReplacements(
   return result;
 }
 
+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;
+  }
+  mkdirSync(dirname(destPath), { recursive: true });
+  if (isTextFile(srcPath)) {
+    const content = readFileSync(srcPath, "utf-8");
+    writeFileSync(destPath, applyReplacements(content, replacements), "utf-8");
+  } else {
+    cpSync(srcPath, destPath);
+  }
+  created.push(destPath);
+}
+
+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);
+    const destPath = join(destDir, entry);
+    if (statSync(srcPath).isDirectory()) {
+      copyDirRecursive(srcPath, destPath, replacements, created, force);
+    } else {
+      copyFile(srcPath, destPath, replacements, created, force);
+    }
+  }
+}
+
+// ── 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.
- *
- * @param targetPath - Directory to scaffold into (will be created if it doesn't exist)
- * @param options - Configuration for placeholder substitution
- * @returns List of files created
  */
 export function initDocsTemplate(
   targetPath: string,
@@ -97,32 +185,52 @@ export function initDocsTemplate(
     throw new Error(`Scaffolding directory not found at ${SCAFFOLDING_DIR}`);
   }
 
-  function copyDir(srcDir: string, destDir: string) {
-    if (!existsSync(destDir)) {
-      mkdirSync(destDir, { recursive: true });
+  copyDirRecursive(SCAFFOLDING_DIR, target, replacements, created, true);
+  return created;
+}
+
+/**
+ * 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: 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(", ")}`,
+      );
     }
 
-    for (const entry of readdirSync(srcDir)) {
-      const srcPath = join(srcDir, entry);
-      const destPath = join(destDir, entry);
-      const stat = statSync(srcPath);
-
-      if (stat.isDirectory()) {
-        copyDir(srcPath, destPath);
-      } else if (isTextFile(srcPath)) {
-        const content = readFileSync(srcPath, "utf-8");
-        const processed = applyReplacements(content, replacements);
-        mkdirSync(dirname(destPath), { recursive: true });
-        writeFileSync(destPath, processed, "utf-8");
-        created.push(destPath);
+    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);
       } else {
-        mkdirSync(dirname(destPath), { recursive: true });
-        cpSync(srcPath, destPath);
-        created.push(destPath);
+        copyFile(srcPath, destPath, replacements, created, options.force);
       }
     }
   }
 
-  copyDir(SCAFFOLDING_DIR, target);
   return created;
 }