@knitli/astro-docs-template 0.2.2 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knitli/astro-docs-template",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Opinionated Astro + Starlight docs site template with Knitli branding",
   "keywords": [
     "knitli",
@@ -37,7 +37,9 @@
     "postbuild": "tsc --noCheck --emitDeclarationOnly --declaration --declarationDir dist",
     "clean": "rm -rf dist",
     "deploy": "bun publish --tag latest",
-    "prepack": "bun run build"
+    "prepack": "bun run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "dependencies": {
     "@astrojs/cloudflare": "^13.1.1",
@@ -69,12 +71,14 @@
     "@astrojs/compiler-rs": "^0.1.4",
     "@biomejs/biome": "^2.4.2",
     "@knitli/tsconfig": "*",
+    "@types/bun": "^1.3.4",
     "@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"
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
   },
   "devEngines": {
     "packageManager": {

package/scaffolding/package.json

@@ -14,14 +14,15 @@
     "wrangler": "bunx wrangler"
   },
   "dependencies": {
-    "@knitli/astro-docs-template": "workspace:*",
-    "@knitli/docs-components": "workspace:*"
+    "@knitli/astro-docs-template": "latest",
+    "@knitli/docs-components": "latest"
   },
   "devDependencies": {
-    "@astrojs/check": "catalog:dev-common",
-    "@types/node": "catalog:types",
-    "typescript": "catalog:dev-common",
-    "wrangler": "catalog:dev-common"
+    "@astrojs/check": "latest",
+    "@knitli/tsconfig": "latest",
+    "@types/node": "latest",
+    "typescript": "latest",
+    "wrangler": "latest"
   },
   "trustedDependencies": [
     "bun"

package/scaffolding/public/robots.txt

@@ -0,0 +1,32 @@
+# As a condition of accessing this website, you agree to abide by the
+# following content signals:
+
+# (a)  If a content-signal = yes, you may collect content for the
+#      corresponding use.
+# (b)  If a content-signal = no, you may not collect content for the
+#      corresponding use.
+# (c)  If the website operator does not include a content signal for a
+#      corresponding use, the website operator neither grants nor restricts
+#      permission via content signal with respect to the corresponding use.
+
+# The content signals and their meanings are:
+
+# search: building a search index and providing search results (e.g., returning
+#         hyperlinks and short excerpts from your website's contents). Search
+#         does not include providing AI-generated search summaries.
+# ai-input: inputting content into one or more AI models (e.g., retrieval
+#           augmented generation, grounding, or other real-time taking of
+#           content for generative AI search answers).
+# ai-train: training or fine-tuning AI models.
+
+# ANY RESTRICTIONS EXPRESSED VIA CONTENT SIGNALS ARE EXPRESS RESERVATIONS OF
+# RIGHTS UNDER ARTICLE 4 OF THE EUROPEAN UNION DIRECTIVE 2019/790 ON COPYRIGHT
+# AND RELATED RIGHTS IN THE DIGITAL SINGLE MARKET.
+
+User-Agent: *
+Content-Signal: ai-train=yes, search=yes, ai-input=yes
+Allow: /
+Disallow: /cdn-cgi/
+Disallow: /admin/
+
+Sitemap: https://docs.knitli.com/sitemap-index.xml

package/scaffolding/tsconfig.json

@@ -1,5 +1,8 @@
 {
-  "extends": "@knitli/tsconfig/astro-tsconfig.json",
+  "extends": "@knitli/tsconfig/astro",
   "include": [".astro/types.d.ts", "**/*"],
-  "exclude": ["dist"]
+  "exclude": ["dist"],
+  "compilerOptions": {
+    "rootDir": "."
+  }
 }

package/src/cli.ts

@@ -15,6 +15,8 @@ import {
   type PieceName,
 } from "./index";
 
+const BINARY_NAME = "knitli-docs";
+
 // ── Arg parsing ──
 
 function parseArgs(argv: string[]) {
@@ -113,7 +115,10 @@ async function getOptions(flags: Record<string, string>): Promise<InitOptions> {
 // ── Commands ──
 
 async function main() {
-  const { flags, positional } = parseArgs(process.argv.slice(2));
+  const rawArgs = process.argv.slice(2);
+  // Strip binary name if passed as first arg (e.g. `bunx @knitli/astro-docs-template -- knitli-docs add`)
+  const args = rawArgs[0] === BINARY_NAME ? rawArgs.slice(1) : rawArgs;
+  const { flags, positional } = parseArgs(args);
   const command = positional[0];
 
   if (flags.help || !command) {

package/src/index.test.ts

@@ -0,0 +1,318 @@
+// SPDX-FileCopyrightText: 2026 Knitli Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+import { existsSync, mkdtempSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  addPieces,
+  initDocsTemplate,
+  mergePackageJsonDeps,
+  normaliseDependencyVersion,
+  PIECE_NAMES,
+  PIECES,
+  type InitOptions,
+} from "./index";
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function makeTmpDir(): string {
+  return mkdtempSync(join(tmpdir(), "knitli-docs-test-"));
+}
+
+const BASE_OPTIONS: InitOptions = {
+  appName: "TestApp",
+  name: "@test/test-docs",
+  description: "Test documentation site",
+  workerName: "test-app-docs",
+};
+
+// ── normaliseDependencyVersion ────────────────────────────────────────────────
+
+describe("normaliseDependencyVersion", () => {
+  it("converts workspace:* to *", () => {
+    expect(normaliseDependencyVersion("workspace:*")).toBe("*");
+  });
+
+  it("strips workspace: prefix from semver ranges, preserving the range", () => {
+    expect(normaliseDependencyVersion("workspace:^1.2.3")).toBe("^1.2.3");
+    expect(normaliseDependencyVersion("workspace:~1.0.0")).toBe("~1.0.0");
+    expect(normaliseDependencyVersion("workspace:>=2.0.0")).toBe(">=2.0.0");
+  });
+
+  it("converts catalog:dev-common to latest", () => {
+    expect(normaliseDependencyVersion("catalog:dev-common")).toBe("latest");
+  });
+
+  it("converts catalog:types to latest", () => {
+    expect(normaliseDependencyVersion("catalog:types")).toBe("latest");
+  });
+
+  it("leaves regular semver ranges unchanged", () => {
+    expect(normaliseDependencyVersion("^1.2.3")).toBe("^1.2.3");
+    expect(normaliseDependencyVersion("~2.0.0")).toBe("~2.0.0");
+    expect(normaliseDependencyVersion("latest")).toBe("latest");
+    expect(normaliseDependencyVersion("*")).toBe("*");
+  });
+});
+
+// ── mergePackageJsonDeps ──────────────────────────────────────────────────────
+
+describe("mergePackageJsonDeps", () => {
+  it("adds template dependencies to an existing package.json", () => {
+    const existing = { name: "my-project", dependencies: { react: "^19.0.0" } };
+    const template = { dependencies: { astro: "^5.0.0" } };
+    const result = mergePackageJsonDeps(existing, template);
+    expect(result.dependencies).toEqual({ react: "^19.0.0", astro: "^5.0.0" });
+  });
+
+  it("template deps take precedence over existing ones for the same package", () => {
+    const existing = { name: "x", dependencies: { astro: "^4.0.0" } };
+    const template = { dependencies: { astro: "^5.0.0" } };
+    const result = mergePackageJsonDeps(existing, template);
+    expect(result.dependencies?.astro).toBe("^5.0.0");
+  });
+
+  it("normalises workspace:* in template deps", () => {
+    const existing = { name: "x" };
+    const template = { dependencies: { "@knitli/astro-docs-template": "workspace:*" } };
+    const result = mergePackageJsonDeps(existing, template);
+    expect(result.dependencies?.["@knitli/astro-docs-template"]).toBe("*");
+  });
+
+  it("normalises catalog:* in template devDependencies", () => {
+    const existing = { name: "x" };
+    const template = { devDependencies: { typescript: "catalog:dev-common" } };
+    const result = mergePackageJsonDeps(existing, template);
+    expect(result.devDependencies?.typescript).toBe("latest");
+  });
+
+  it("merges devDependencies", () => {
+    const existing = { name: "x", devDependencies: { vitest: "^4.0.0" } };
+    const template = { devDependencies: { typescript: "catalog:dev-common", "@types/node": "catalog:types" } };
+    const result = mergePackageJsonDeps(existing, template);
+    expect(result.devDependencies).toEqual({
+      vitest: "^4.0.0",
+      typescript: "latest",
+      "@types/node": "latest",
+    });
+  });
+
+  it("merges peerDependencies", () => {
+    const existing = { name: "x" };
+    const template = { peerDependencies: { astro: ">=5.0.0" } };
+    const result = mergePackageJsonDeps(existing, template);
+    expect(result.peerDependencies).toEqual({ astro: ">=5.0.0" });
+  });
+
+  it("does not touch name, version, scripts, or other fields", () => {
+    const existing = { name: "my-app", version: "1.2.3", scripts: { build: "tsc" }, private: true };
+    const template = { name: "template", version: "0.0.1", scripts: { dev: "astro dev" }, dependencies: { astro: "*" } };
+    const result = mergePackageJsonDeps(existing, template);
+    expect(result.name).toBe("my-app");
+    expect(result.version).toBe("1.2.3");
+    expect(result.scripts).toEqual({ build: "tsc" });
+    expect(result.private).toBe(true);
+  });
+
+  it("handles missing dependency fields gracefully", () => {
+    const existing = { name: "x" };
+    const template = { name: "t" };
+    const result = mergePackageJsonDeps(existing, template);
+    expect(result.dependencies).toBeUndefined();
+    expect(result.devDependencies).toBeUndefined();
+  });
+});
+
+// ── initDocsTemplate ──────────────────────────────────────────────────────────
+
+describe("initDocsTemplate", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("creates files in the target directory", () => {
+    const created = initDocsTemplate(tmpDir, BASE_OPTIONS);
+    expect(created.length).toBeGreaterThan(0);
+  });
+
+  it("applies placeholder substitutions", () => {
+    initDocsTemplate(tmpDir, BASE_OPTIONS);
+    const pkg = JSON.parse(readFileSync(join(tmpDir, "package.json"), "utf-8"));
+    expect(pkg.name).toBe(BASE_OPTIONS.name);
+  });
+
+  it("substitutes {{appName}} in text files", () => {
+    initDocsTemplate(tmpDir, BASE_OPTIONS);
+    const wrangler = readFileSync(join(tmpDir, "wrangler.jsonc"), "utf-8");
+    expect(wrangler).toContain(BASE_OPTIONS.workerName);
+    expect(wrangler).not.toContain("{{workerName}}");
+  });
+
+  it("always clobbers existing files (init always overwrites, no flag needed)", () => {
+    // Write an existing file that will be overwritten
+    writeFileSync(join(tmpDir, "tsconfig.json"), '{"compilerOptions":{}}', "utf-8");
+    const created = initDocsTemplate(tmpDir, BASE_OPTIONS);
+    // tsconfig.json should have been re-created
+    expect(created.some((f) => f.includes("tsconfig.json"))).toBe(true);
+  });
+
+  it("creates all expected piece files", () => {
+    initDocsTemplate(tmpDir, BASE_OPTIONS);
+    expect(existsSync(join(tmpDir, "astro.config.ts"))).toBe(true);
+    expect(existsSync(join(tmpDir, "wrangler.jsonc"))).toBe(true);
+    expect(existsSync(join(tmpDir, "tsconfig.json"))).toBe(true);
+    expect(existsSync(join(tmpDir, "package.json"))).toBe(true);
+    expect(existsSync(join(tmpDir, "mise.toml"))).toBe(true);
+    expect(existsSync(join(tmpDir, "src/content.config.ts"))).toBe(true);
+    expect(existsSync(join(tmpDir, "src/env.d.ts"))).toBe(true);
+    expect(existsSync(join(tmpDir, "src/styles/custom.css"))).toBe(true);
+  });
+});
+
+// ── addPieces ─────────────────────────────────────────────────────────────────
+
+describe("addPieces", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("creates the requested file when it does not exist", () => {
+    const created = addPieces(tmpDir, { ...BASE_OPTIONS, pieces: ["tsconfig"] });
+    expect(created.length).toBe(1);
+    expect(existsSync(join(tmpDir, "tsconfig.json"))).toBe(true);
+  });
+
+  it("skips an existing non-package.json file without --force", () => {
+    // Pre-populate the tsconfig so it already exists
+    writeFileSync(join(tmpDir, "tsconfig.json"), '{"existing":true}', "utf-8");
+    const created = addPieces(tmpDir, { ...BASE_OPTIONS, pieces: ["tsconfig"] });
+    expect(created.length).toBe(0);
+    // Original content should be intact
+    const content = JSON.parse(readFileSync(join(tmpDir, "tsconfig.json"), "utf-8"));
+    expect(content.existing).toBe(true);
+  });
+
+  it("overwrites an existing non-package.json file with --force", () => {
+    writeFileSync(join(tmpDir, "tsconfig.json"), '{"existing":true}', "utf-8");
+    const created = addPieces(tmpDir, { ...BASE_OPTIONS, pieces: ["tsconfig"], force: true });
+    expect(created.length).toBe(1);
+    const content = JSON.parse(readFileSync(join(tmpDir, "tsconfig.json"), "utf-8"));
+    expect(content.existing).toBeUndefined();
+  });
+
+  it("applies placeholder substitutions to added files", () => {
+    addPieces(tmpDir, { ...BASE_OPTIONS, pieces: ["wrangler"] });
+    const content = readFileSync(join(tmpDir, "wrangler.jsonc"), "utf-8");
+    expect(content).not.toContain("{{workerName}}");
+    expect(content).toContain(BASE_OPTIONS.workerName);
+  });
+
+  // ── deps piece (the main bug fix) ─────────────────────────────────────────
+
+  describe("deps piece", () => {
+    it("creates package.json when it does not exist", () => {
+      const created = addPieces(tmpDir, { ...BASE_OPTIONS, pieces: ["deps"] });
+      expect(created.length).toBe(1);
+      expect(existsSync(join(tmpDir, "package.json"))).toBe(true);
+    });
+
+    it("merges deps into an existing package.json instead of skipping", () => {
+      const existingPkg = {
+        name: "my-other-project",
+        version: "3.0.0",
+        private: true,
+        dependencies: { express: "^4.0.0" },
+      };
+      writeFileSync(join(tmpDir, "package.json"), JSON.stringify(existingPkg, null, 2), "utf-8");
+
+      const created = addPieces(tmpDir, { ...BASE_OPTIONS, pieces: ["deps"] });
+      // Should be modified (not 0 files)
+      expect(created.length).toBe(1);
+
+      const merged = JSON.parse(readFileSync(join(tmpDir, "package.json"), "utf-8"));
+      // Existing non-dep fields are preserved
+      expect(merged.name).toBe("my-other-project");
+      expect(merged.version).toBe("3.0.0");
+      expect(merged.private).toBe(true);
+      // Existing dep is preserved
+      expect(merged.dependencies.express).toBe("^4.0.0");
+      // Template deps are added
+      expect(merged.dependencies["@knitli/astro-docs-template"]).toBeDefined();
+      expect(merged.devDependencies?.["@astrojs/check"]).toBeDefined();
+    });
+
+    it("normalises workspace:* references when merging", () => {
+      writeFileSync(join(tmpDir, "package.json"), '{"name":"x","dependencies":{}}', "utf-8");
+      addPieces(tmpDir, { ...BASE_OPTIONS, pieces: ["deps"] });
+      const merged = JSON.parse(readFileSync(join(tmpDir, "package.json"), "utf-8"));
+      // workspace:* should be normalised away
+      const allVersions = Object.values({
+        ...merged.dependencies,
+        ...merged.devDependencies,
+      }) as string[];
+      expect(allVersions.some((v) => v.startsWith("workspace:"))).toBe(false);
+      expect(allVersions.some((v) => v.startsWith("catalog:"))).toBe(false);
+    });
+
+    it("throws a helpful error when existing package.json is not valid JSON", () => {
+      writeFileSync(join(tmpDir, "package.json"), "{ this is not valid json", "utf-8");
+      expect(() =>
+        addPieces(tmpDir, { ...BASE_OPTIONS, pieces: ["deps"] }),
+      ).toThrow(/Failed to parse existing package\.json/);
+    });
+
+    it("replaces existing package.json wholesale with --force", () => {
+      const existingPkg = { name: "my-other-project", version: "3.0.0", scripts: { start: "node server.js" } };
+      writeFileSync(join(tmpDir, "package.json"), JSON.stringify(existingPkg, null, 2), "utf-8");
+
+      addPieces(tmpDir, { ...BASE_OPTIONS, pieces: ["deps"], force: true });
+      const result = JSON.parse(readFileSync(join(tmpDir, "package.json"), "utf-8"));
+      // Should be the template's package.json content (with substitution applied)
+      expect(result.name).toBe(BASE_OPTIONS.name);
+    });
+  });
+
+  // ── content piece ─────────────────────────────────────────────────────────
+
+  it("copies directory pieces (starter-content)", () => {
+    const created = addPieces(tmpDir, { ...BASE_OPTIONS, pieces: ["starter-content"] });
+    expect(created.length).toBeGreaterThan(0);
+    expect(existsSync(join(tmpDir, "src/content/docs"))).toBe(true);
+  });
+
+  // ── multiple pieces ───────────────────────────────────────────────────────
+
+  it("can add multiple pieces at once", () => {
+    const created = addPieces(tmpDir, { ...BASE_OPTIONS, pieces: ["tsconfig", "styles"] });
+    expect(existsSync(join(tmpDir, "tsconfig.json"))).toBe(true);
+    expect(existsSync(join(tmpDir, "src/styles/custom.css"))).toBe(true);
+    expect(created.length).toBe(2);
+  });
+
+  // ── validation ────────────────────────────────────────────────────────────
+
+  it("throws for an unknown piece name", () => {
+    expect(() =>
+      addPieces(tmpDir, { ...BASE_OPTIONS, pieces: ["nonexistent" as never] }),
+    ).toThrow(/Unknown piece/);
+  });
+
+  it("PIECE_NAMES lists all defined pieces", () => {
+    expect(PIECE_NAMES).toEqual(Object.keys(PIECES));
+  });
+});

package/src/index.ts

@@ -165,6 +165,116 @@ function copyDirRecursive(
   }
 }
 
+/**
+ * Normalise a dependency version specifier so that workspace-protocol and
+ * catalog entries from the Knitli monorepo become portable version strings
+ * usable in any project.
+ *
+ *   "workspace:*"        → "*"
+ *   "workspace:^1.2.3"   → "^1.2.3"
+ *   "catalog:something"  → "latest"
+ *   anything else        → unchanged
+ */
+export function normaliseDependencyVersion(version: string): string {
+  if (version.startsWith("workspace:")) {
+    const spec = version.slice("workspace:".length).trim();
+    if (spec === "" || spec === "*") return "*";
+    return spec;
+  }
+  if (version.startsWith("catalog:")) return "latest";
+  return version;
+}
+
+type PackageJsonDeps = Record<string, string>;
+type PackageJsonLike = {
+  dependencies?: PackageJsonDeps;
+  devDependencies?: PackageJsonDeps;
+  peerDependencies?: PackageJsonDeps;
+  [key: string]: unknown;
+};
+
+/**
+ * Merge the `dependencies`, `devDependencies`, and `peerDependencies` from
+ * `templatePkg` into `existingPkg`, normalising any monorepo-specific version
+ * specifiers so the result is portable.  Template entries take precedence over
+ * existing entries for the same package name.
+ *
+ * All other fields (name, version, scripts, …) in `existingPkg` are left
+ * untouched.
+ */
+export function mergePackageJsonDeps(
+  existingPkg: PackageJsonLike,
+  templatePkg: PackageJsonLike,
+): PackageJsonLike {
+  const result: PackageJsonLike = { ...existingPkg };
+  const depFields = [
+    "dependencies",
+    "devDependencies",
+    "peerDependencies",
+  ] as const;
+  for (const field of depFields) {
+    const templateDeps = templatePkg[field];
+    if (!templateDeps || Object.keys(templateDeps).length === 0) continue;
+    const normalised: PackageJsonDeps = {};
+    for (const [pkg, version] of Object.entries(templateDeps)) {
+      normalised[pkg] = normaliseDependencyVersion(version);
+    }
+    result[field] = { ...(existingPkg[field] ?? {}), ...normalised };
+  }
+  return result;
+}
+
+/**
+ * Merge template `package.json` dependencies into an existing one.
+ *
+ * - If the destination does not exist yet, the file is simply copied
+ *   (with placeholder substitution).
+ * - If `force` is set, the file is overwritten wholesale.
+ * - Otherwise the `dependencies`, `devDependencies`, and `peerDependencies`
+ *   from the template are merged into the existing file, normalising any
+ *   workspace-protocol / catalog version specifiers to portable equivalents.
+ *
+ * **Note**: the merged file is re-serialised with 2-space indentation using
+ * `JSON.stringify`. Any bespoke formatting or key ordering in the original
+ * file will not be preserved.
+ */
+function mergeOrCopyPackageJson(
+  srcPath: string,
+  destPath: string,
+  replacements: Record<string, string>,
+  created: string[],
+  force?: boolean,
+): void {
+  if (!existsSync(destPath) || force) {
+    copyFile(srcPath, destPath, replacements, created, force);
+    return;
+  }
+
+  const templateRaw = applyReplacements(
+    readFileSync(srcPath, "utf-8"),
+    replacements,
+  );
+  const templatePkg = JSON.parse(templateRaw) as PackageJsonLike;
+
+  let existingPkg: PackageJsonLike;
+  try {
+    existingPkg = JSON.parse(readFileSync(destPath, "utf-8")) as PackageJsonLike;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `Failed to parse existing package.json at ${destPath}: ${msg}\n` +
+        "Fix or remove the file and try again.",
+    );
+  }
+
+  const merged = mergePackageJsonDeps(existingPkg, templatePkg);
+
+  mkdirSync(dirname(destPath), { recursive: true });
+  writeFileSync(destPath, `${JSON.stringify(merged, null, 2)}\n`, "utf-8");
+  created.push(destPath);
+  console.log(`  merged deps into ${destPath}`);
+}
+
 // ── Public API ──
 
 /**
@@ -172,6 +282,9 @@ function copyDirRecursive(
  *
  * Copies all files from the scaffolding directory to the target path,
  * applying placeholder substitution to text files.
+ *
+ * **Note**: all files are written unconditionally — existing files are always
+ * overwritten.  For selective, non-destructive installation use `addPieces`.
  */
 export function initDocsTemplate(
   targetPath: string,
@@ -232,6 +345,14 @@ export function addPieces(
           created,
           options.force,
         );
+      } else if (relPath === "package.json") {
+        mergeOrCopyPackageJson(
+          srcPath,
+          destPath,
+          replacements,
+          created,
+          options.force,
+        );
       } else {
         copyFile(srcPath, destPath, replacements, created, options.force);
       }