@ghostbyte/agent-docs-kit 5.0.0 → 5.0.1

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 Notable user-visible changes are recorded here. Versions follow semantic versioning.
 
+## Unreleased
+
+### Fixed
+
+- Local documentation workspaces and generated audit records are excluded from the npm archive by an explicit public-document allowlist.
+- Package validation and smoke installation now reject missing declared entry points and unexpected documentation files.
+- The legacy `main` field resolves to the same public API used by `exports`.
+- Forced scaffold replacement stages content before swapping the owned file into place.
+
+### Changed
+
+- GitHub workflows use the reviewed, SHA-pinned checkout v7.0.1, setup-node v7.1.0, configure-pages v6.0.0, upload-pages-artifact v5.0.0, and deploy-pages v5.0.1 releases.
+
 ## 5.0.0 - 2026-10-14
 
 ### Added

package/docs/ARCHITECTURE.md

@@ -43,4 +43,6 @@ Agent_Docs_Kit/
 
 `content/` is the single canonical library for all three workflows. `agent-docs setup` creates `.agent-docs/config.json` and a project documentation tree. Reports are written beneath configured directories; the reference library stays in the npm package and installed skill rather than being duplicated into each project.
 
-Generated outputs under `build/`, package archives, dependencies, and the maintainer’s local monthly AI prompt are ignored by Git.
+Generated outputs under `build/`, package archives, dependencies, and the maintainer’s local monthly AI prompt are ignored by Git. Local consumer-style documentation under the configured `docs/` workspace is also ignored in this repository.
+
+Git ignore rules are not treated as a publishing boundary. `package.json` explicitly lists the six public maintainer guides, `docs/.npmignore` excludes local workspace records, and the packed-installation smoke test rejects every unexpected `docs/` path and every missing declared entry point.

package/docs/RELEASE_PROCESS.md

@@ -4,7 +4,7 @@ Published npm versions are immutable. A matching version-tag push can publish a
 
 1. Update canonical content and run `npm run build` to refresh progressive skill references and the site.
 2. Run `npm run release:check`. This includes tests, validation, builds, a clean tarball installation, and `npm audit`.
-3. Confirm the package archive contains no credentials, local reports, nested repositories, or generated consumer data.
+3. Confirm the package archive contains no credentials, local reports, nested repositories, or generated consumer data. `npm pack --dry-run --json` must show only the six approved public files under `docs/`, and every `main`, `bin`, and `exports` target must exist in the archive.
 4. Commit the package changes locally.
 5. Update the version with `npm version patch`, `minor`, or `major` according to compatibility.
 6. Push the commit and tag. A matching `v*` tag on `main` runs `.github/workflows/publish-npm.yml`, verifies the version and ancestry, and publishes through npm trusted publishing.

package/docs/SECURITY_MODEL.md

@@ -4,6 +4,8 @@ The CLI is inert on installation: `package.json` defines no `preinstall`, `insta
 
 Project setup skips existing files by default. `--force` is required to replace files owned by a command, and `--dry-run` previews writes. The package does not install Git hooks automatically, execute network scans, read credentials, or contact a telemetry service.
 
+Forced scaffold replacement is staged in the destination directory before the owned file is swapped into place. npm packaging uses an explicit public-document allowlist plus a packed-manifest check; local documentation, generated findings, and audit evidence are rejected from the archive even when they exist in the working tree.
+
 Audit reports begin as `Unverified`. The tool scaffolds the review; it does not claim that generated text proves a control. Agents and reviewers must attach repository paths, line numbers, reproducible command output, or authorized external evidence.
 
 Publishing uses npm provenance through GitHub trusted publishing when configured. Protect the GitHub release environment, require reviews as appropriate, and never store a long-lived npm token when OIDC is available.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghostbyte/agent-docs-kit",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "description": "Documentation governance, evidence-based security audits, and engineering-quality reviews for software projects.",
   "type": "module",
   "bin": {
@@ -15,7 +15,12 @@
     "content/",
     "templates/",
     "skills/",
-    "docs/",
+    "docs/ARCHITECTURE.md",
+    "docs/CONTENT_MAINTENANCE.md",
+    "docs/GITHUB_AND_NPM_SETUP.md",
+    "docs/PURPOSE.md",
+    "docs/RELEASE_PROCESS.md",
+    "docs/SECURITY_MODEL.md",
     "scripts/",
     "site/",
     "tests/",
@@ -62,5 +67,6 @@
   "directories": {
     "doc": "docs",
     "test": "tests"
-  }
+  },
+  "main": "./src/api/index.mjs"
 }

package/scripts/smoke-package.mjs

@@ -13,11 +13,35 @@ try {
   const cache = resolve(scratch, "npm-cache");
   const packed = JSON.parse(runNpm(["pack", "--json", "--cache", cache, "--pack-destination", scratch], { cwd: root, encoding: "utf8" }));
   const archivePaths = new Set(packed[0].files.map((entry) => entry.path.replaceAll("\\", "/")));
+  const publicDocs = new Set([
+    "docs/ARCHITECTURE.md",
+    "docs/CONTENT_MAINTENANCE.md",
+    "docs/GITHUB_AND_NPM_SETUP.md",
+    "docs/PURPOSE.md",
+    "docs/RELEASE_PROCESS.md",
+    "docs/SECURITY_MODEL.md"
+  ]);
   for (const required of ["scripts/validate-content.mjs", "site/index.html", "tests/cli.test.mjs", "skills/manage-project-quality/references/security-protocol.md", "skills/manage-project-quality/references/engineering-protocol.md", "skills/manage-project-quality/references/documentation-governance.md"]) {
     if (!archivePaths.has(required)) throw new Error(`Packed archive is missing ${required}.`);
   }
+  for (const publicDoc of publicDocs) {
+    if (!archivePaths.has(publicDoc)) throw new Error(`Packed archive is missing public documentation: ${publicDoc}`);
+  }
   for (const path of archivePaths) {
     if (/^(?:\.git|\.agent-docs|\.npm-cache|build|node_modules)(?:\/|$)|MONTHLY_MAINTENANCE_AI\.md$|\.tgz$/i.test(path)) throw new Error(`Private or generated path leaked into package: ${path}`);
+    if (path.startsWith("docs/") && !publicDocs.has(path)) throw new Error(`Local documentation leaked into package: ${path}`);
+  }
+  const packageMetadata = JSON.parse(await readFile(resolve(root, "package.json"), "utf8"));
+  const declaredTargets = new Set([packageMetadata.main, ...Object.values(packageMetadata.bin ?? {})]);
+  const collectExportTargets = (value) => {
+    if (typeof value === "string") declaredTargets.add(value);
+    else if (Array.isArray(value)) value.forEach(collectExportTargets);
+    else if (value && typeof value === "object") Object.values(value).forEach(collectExportTargets);
+  };
+  collectExportTargets(packageMetadata.exports);
+  for (const target of declaredTargets) {
+    const normalized = target?.replace(/^\.\//, "").replaceAll("\\", "/");
+    if (normalized && !archivePaths.has(normalized)) throw new Error(`Declared package entry point is missing from the archive: ${target}`);
   }
   const tarball = resolve(scratch, packed[0].filename);
   const consumer = resolve(scratch, "consumer");

package/scripts/validate-content.mjs

@@ -74,6 +74,18 @@ for (const directory of metadata.files ?? []) {
   try { await access(resolve(root, directory)); }
   catch { errors.push(`package.json files entry does not exist: ${directory}`); }
 }
+const declaredTargets = new Set([metadata.main, ...Object.values(metadata.bin ?? {})]);
+const collectExportTargets = (value) => {
+  if (typeof value === "string") declaredTargets.add(value);
+  else if (Array.isArray(value)) value.forEach(collectExportTargets);
+  else if (value && typeof value === "object") Object.values(value).forEach(collectExportTargets);
+};
+collectExportTargets(metadata.exports);
+for (const target of declaredTargets) {
+  if (!target) continue;
+  try { await access(resolve(root, target)); }
+  catch { errors.push(`Declared package entry point does not exist: ${target}`); }
+}
 
 const site = await readFile(resolve(root, "site/index.html"), "utf8");
 const ids = [...site.matchAll(/\sid="([^"]+)"/g)].map((match) => match[1]);

package/src/core/files.mjs

@@ -16,10 +16,31 @@ export async function writeSafe(path, contents, { force = false, dryRun = false
   if (!force && await exists(path)) return { path, status: "skipped" };
   if (!dryRun) {
     await mkdir(dirname(path), { recursive: true });
-    try { await writeFile(path, contents, { encoding: "utf8", flag: force ? "w" : "wx" }); }
-    catch (error) {
-      if (!force && error.code === "EEXIST") return { path, status: "skipped" };
-      throw error;
+    if (!force) {
+      try { await writeFile(path, contents, { encoding: "utf8", flag: "wx" }); }
+      catch (error) {
+        if (error.code === "EEXIST") return { path, status: "skipped" };
+        throw error;
+      }
+    } else {
+      const nonce = `${process.pid}-${Date.now()}-${randomUUID()}`;
+      const staged = `${path}.agent-docs-stage-${nonce}`;
+      const backup = `${path}.agent-docs-backup-${nonce}`;
+      await writeFile(staged, contents, { encoding: "utf8", flag: "wx" });
+      const replacing = await exists(path);
+      let movedOriginal = false;
+      try {
+        if (replacing) {
+          await rename(path, backup);
+          movedOriginal = true;
+        }
+        await rename(staged, path);
+      } catch (error) {
+        await rm(staged, { force: true });
+        if (movedOriginal && !(await exists(path))) await rename(backup, path);
+        throw error;
+      }
+      if (movedOriginal) await rm(backup, { force: true });
     }
   }
   return { path, status: dryRun ? "planned" : "created" };

package/tests/cli.test.mjs

@@ -1,6 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { access, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { access, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { setupProject } from "../src/commands/setup.mjs";
@@ -29,6 +29,22 @@ test("setup is explicit, non-destructive, and repeatable", async () => {
   }
 });
 
+test("forced setup atomically replaces owned files without leaving staging artifacts", async () => {
+  const root = await mkdtemp(join(tmpdir(), "agent-docs-kit-"));
+  try {
+    await setupProject({ cwd: root });
+    const overview = join(root, "docs", "01-system", "overview.md");
+    await writeFile(overview, "temporary contents\n");
+    const replaced = await setupProject({ cwd: root, force: true });
+    assert.ok(replaced.every((item) => item.status === "created"));
+    assert.match(await readFile(overview, "utf8"), /^# System overview/);
+    const names = await readdir(join(root, "docs", "01-system"));
+    assert.ok(names.every((name) => !name.includes(".agent-docs-stage-") && !name.includes(".agent-docs-backup-")));
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
 test("security and engineering reports use distinct semantics", async () => {
   const root = await mkdtemp(join(tmpdir(), "agent-docs-kit-"));
   try {