@knitli/astro-docs-template 0.1.2 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knitli/astro-docs-template",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Opinionated Astro + Starlight docs site template with Knitli branding",
   "keywords": [
     "knitli",
@@ -19,67 +19,62 @@
   "author": "Knitli Inc.",
   "type": "module",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./config": {
-      "types": "./dist/config.d.ts",
-      "import": "./dist/config.js"
-    }
+    ".": "./src/index.ts",
+    "./config": "./src/config.ts"
   },
   "bin": {
-    "knitli-docs": "dist/cli.js"
+    "knitli-docs": "src/cli.ts"
   },
   "files": [
-    "dist",
+    "src",
     "scaffolding",
     "README.md",
     "CHANGELOG.md"
   ],
   "scripts": {
-    "build": "vite build && tsc --emitDeclarationOnly --noCheck --noEmit false",
-    "prepublishOnly": "bun run build",
-    "publish": "npm publish --access public",
-    "typecheck": "bunx tsc --noEmit"
+    "prebuild": "bun run clean",
+    "build": "bun run build.ts",
+    "postbuild": "tsc --noCheck --emitDeclarationOnly --declaration --declarationDir dist",
+    "clean": "rm -rf dist",
+    "deploy": "bun publish --tag latest",
+    "prepack": "bun run build"
   },
   "dependencies": {
-    "@astrojs/cloudflare": "catalog:astro-core",
-    "@astrojs/markdoc": "catalog:astro-plugins",
-    "@astrojs/mdx": "catalog:astro-core",
-    "@astrojs/sitemap": "catalog:astro-core",
-    "@astrojs/starlight": "catalog:astro-core",
-    "@knitli/docs-components": "workspace:*",
-    "@nuasite/llm-enhancements": "catalog:astro-plugins",
-    "astro": "catalog:astro-core",
-    "astro-cloudflare-pages-headers": "catalog:astro-plugins",
-    "astro-d2": "catalog:astro-plugins",
-    "astro-favicons": "catalog:astro-core",
+    "@astrojs/cloudflare": "^13.1.1",
+    "@astrojs/markdoc": "^1.0.0",
+    "@astrojs/mdx": "^5.0.0",
+    "@astrojs/sitemap": "^3.6.0",
+    "@astrojs/starlight": "^0.38.1",
+    "@knitli/docs-components": "1.3.6",
+    "@nuasite/llm-enhancements": "^0.18.0",
+    "astro": "^6.0.4",
+    "astro-cloudflare-pages-headers": "^1.7.7",
+    "astro-d2": "^0.10.0",
+    "astro-favicons": "3.1.6",
     "rehype-external-links": "^3.0.0",
-    "starlight-announcement": "catalog:starlight-plugins",
-    "starlight-changelogs": "catalog:starlight-plugins",
-    "starlight-heading-badges": "catalog:starlight-plugins",
-    "starlight-links-validator": "catalog:starlight-plugins",
-    "starlight-llms-txt": "catalog:starlight-plugins",
-    "starlight-page-actions": "catalog:starlight-plugins",
-    "starlight-plugin-icons": "catalog:starlight-plugins",
-    "starlight-scroll-to-top": "catalog:starlight-plugins",
-    "starlight-sidebar-topics": "catalog:starlight-plugins",
-    "starlight-tags": "catalog:starlight-plugins",
-    "vite-tsconfig-paths": "catalog:dev-common"
+    "starlight-announcement": ">=0.1.1",
+    "starlight-changelogs": " >=0.1.0",
+    "starlight-heading-badges": ">=0.6.1",
+    "starlight-links-validator": ">=0.1.0",
+    "starlight-llms-txt": ">=0.8.0",
+    "starlight-page-actions": ">=0.1.0",
+    "starlight-plugin-icons": ">=0.1.0",
+    "starlight-scroll-to-top": ">=0.4.0",
+    "starlight-sidebar-topics": ">=0.7.1",
+    "starlight-tags": ">=0.4.0",
+    "vite-tsconfig-paths": "6.1.1"
   },
   "devDependencies": {
-    "@astrojs/check": "catalog:dev-common",
-    "@astrojs/compiler-rs": "catalog:astro-core",
-    "@biomejs/biome": "catalog:dev-common",
-    "@knitli/tsconfig": "*",
-    "@types/node": "catalog:types",
-    "bun": "catalog:dev-common",
-    "lightningcss": "catalog:optimization",
-    "sharp": "catalog:astro-core",
-    "svgo": "catalog:optimization",
-    "typescript": "catalog:dev-common",
-    "vite": "catalog:dev-common"
+    "@astrojs/check": "^0.9.6",
+    "@astrojs/compiler-rs": "^0.1.4",
+    "@biomejs/biome": "^2.4.2",
+    "@knitli/tsconfig": "0.2.0",
+    "@types/node": "^24.0.2",
+    "bun": "^1.3.9",
+    "lightningcss": "^1.30.2",
+    "sharp": "^0.34.5",
+    "svgo": "^4.0.0",
+    "typescript": "^5.9.3"
   },
   "devEngines": {
     "packageManager": {
@@ -87,5 +82,11 @@
       "version": "catalog:dev-common",
       "onFail": "download"
     }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false,
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest"
   }
 }

package/scaffolding/package.json

@@ -5,12 +5,11 @@
   "type": "module",
   "scripts": {
     "astro": "bunx astro",
-    "prepare": "test -f ./node_modules/bun/install.js && node ./node_modules/bun/install.js || true",
-
     "prebuild": "bunx wrangler types; bunx astro sync",
     "build": "bunx astro build",
     "deploy": "bun run build && bunx wrangler deploy",
     "dev": "bunx astro dev",
+    "prepare": "test -f ./node_modules/bun/install.js && node ./node_modules/bun/install.js || true",
     "preview": "bunx astro preview",
     "wrangler": "bunx wrangler"
   },

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

@@ -1,25 +1,54 @@
 #!/usr/bin/env bun
-import { stdout, stdin } from 'node:process';
-import { createInterface } from 'node:readline/promises';
-import { PIECES, PIECE_NAMES, addPieces, initDocsTemplate } from './index.js';
 
-function parseArgs(argv) {
-  const flags = {};
-  const positional = [];
+// SPDX-FileCopyrightText: 2026 Knitli Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+import { stdin, stdout } from "node:process";
+import { createInterface } from "node:readline/promises";
+import {
+  addPieces,
+  type InitOptions,
+  initDocsTemplate,
+  PIECE_NAMES,
+  PIECES,
+  type PieceName,
+} from "./index";
+
+// ── 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 === undefined) {
+      continue;
+    }
+
     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 if (arg.startsWith("--")) {
+      const nextArg = argv[i + 1];
+      if (nextArg !== undefined) {
+        flags[arg.slice(2)] = nextArg;
+        i++;
+      } else {
+        positional.push(arg);
+      }
     } else {
       positional.push(arg);
     }
   }
+
   return { flags, positional };
 }
+
+// ── Help text ──
+
 const HELP = `knitli-docs — scaffold and manage Knitli docs sites
 
 Usage:
@@ -28,7 +57,9 @@ Usage:
   knitli-docs list                        Show available pieces
 
 Pieces:
-${Object.entries(PIECES).map(([name, { description }]) => `  ${name.padEnd(18)} ${description}`).join("\n")}
+${Object.entries(PIECES)
+  .map(([name, { description }]) => `  ${name.padEnd(18)} ${description}`)
+  .join("\n")}
 
 Options:
   --app-name <name>       Product name (e.g. "Recoco")
@@ -39,37 +70,57 @@ Options:
   --force, -f             Overwrite existing files
   --help, -h              Show this help
 `;
-async function getOptions(flags) {
+
+// ── Interactive prompts ──
+
+async function getOptions(flags: Record<string, string>): Promise<InitOptions> {
   const rl = createInterface({ input: stdin, output: stdout });
-  const ask = async (question, defaultValue) => {
+
+  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)");
+    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`);
+
+    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");
@@ -82,55 +133,54 @@ async function main() {
       console.log();
       break;
     }
+
     case "init": {
       const dir = flags.dir || positional[1] || ".";
       const options = await getOptions(flags);
-      console.log(`
-Scaffolding into ${dir} ...
-`);
+      console.log(`\nScaffolding into ${dir} ...\n`);
       const created = initDocsTemplate(dir, options);
-      console.log(`
-Done — ${created.length} files created`);
+      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."
+          "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)
+        (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(`
-Adding ${pieces.join(", ")} to ${dir} ...
-`);
+      console.log(`\nAdding ${pieces.join(", ")} to ${dir} ...\n`);
       const created = addPieces(dir, {
         ...options,
-        pieces,
-        force: flags.force === "true"
+        pieces: pieces as PieceName[],
+        force: flags.force === "true",
       });
-      console.log(`
-Done — ${created.length} files created`);
+      console.log(`\nDone — ${created.length} files created`);
       break;
     }
+
     default: {
-      console.error(`Unknown command: ${command}
-`);
+      console.error(`Unknown command: ${command}\n`);
       console.log(HELP);
       process.exit(1);
     }
   }
 }
+
 main().catch((err) => {
   console.error(err.message);
   process.exit(1);