gutterpress 0.11.16-alpha.5 → 0.11.16-alpha.6

package/README.md

@@ -178,6 +178,10 @@ build-and-open instead. `--manifest` applies only to those one-shot PDF/PDF-X
 modes; live HTML preview discovers the project manifest from its input
 directory.
 
+Before it loads plugins, `preview` downloads any pinned npm extension whose
+copy is missing (see [Restoring pinned extensions](#restoring-pinned-extensions)).
+If that fails it warns and previews anyway; the one-shot PDF modes fail fast.
+
 ```sh
 gutterpress preview [input-dir] [options]
 
@@ -204,6 +208,8 @@ gutterpress preview [input-dir] [options]
 
 Build a PDF (default) or HTML output. Pipeline: `validate:pre → convert → assets → build → validate:post`. The CSS print-safety check (remote urls, risky print effects, page-containment) runs once, inside `validate:pre`, as the `source.stylelint` check — there is no separate lint phase.
 
+Before it loads plugins, `build` downloads any pinned npm extension whose copy is missing — a fresh clone has the pins but not the files — and prints one `Downloaded name@version (pinned in manifest.yaml)` line per package. If a download fails, the build stops and names the extension, why, and how to retry. See [Restoring pinned extensions](#restoring-pinned-extensions).
+
 ```sh
 gutterpress build [input-dir] [options]
 
@@ -272,7 +278,7 @@ gutterpress publish --provider gdrive ./my-book
 
 Run the validation pipeline (pre-build source checks and/or post-build PDF checks). Tools that aren't installed are skipped with a warning — they don't fail the run. See [User Guide: Chapter 6 — Validation](https://github.com/dimm-city/gutterpress/blob/main/examples/gutterpress-user-guide/06-validation.md) for the full check list and [User Guide: Chapter 7 — System Setup](https://github.com/dimm-city/gutterpress/blob/main/examples/gutterpress-user-guide/07-system-setup.md) for which external tools each check needs.
 
-The positional directory and `--pdf`/`--input` are independent: the positional (or `--input`) sets the pre-build source directory, `--pdf` separately points at a built PDF for post-build checks. `--input` overrides the positional if both are given.
+The positional directory and `--pdf`/`--input` are independent: the positional (or `--input`) sets the pre-build source directory, `--pdf` separately points at a built PDF for post-build checks. `--input` overrides the positional if both are given. When a source directory is given, missing pinned npm extensions are downloaded first, as for `build` (a failed download exits 3 with the reason). This holds for `preflight` too. The `Downloaded …` lines go to stderr, so `--format json` output stays parseable.
 
 ```sh
 gutterpress validate [dir] [options]
@@ -392,6 +398,31 @@ Add an extension. What `SOURCE` is decides what happens:
 Adding something already listed re-pins or updates that entry instead of
 adding a second one.
 
+An npm install also makes sure the book's `.gitignore` ignores `plugins/npm/`
+(append-only; an author's own `!plugins/npm/` re-include is respected and the
+install warns that downloaded extensions shouldn't be committed). The manifest
+pin is what travels with the book; the downloaded copy does not.
+
+##### Restoring pinned extensions
+
+A fresh clone has `manifest.yaml`'s `name@version` pins but not the downloaded
+copies under `plugins/npm/`. `build`, `validate`, `preflight` and `preview`
+download any missing (or incomplete) pinned version before they load plugins —
+exactly the pinned version, through the same registry-resolved, hash-verified,
+load-tested install as `ext add`, without touching the manifest. Builds and
+checks do it inside the shared plugin-loading step, so every build and export
+(including the desktop's) and every check run does it, and fails with the
+extension, the reason and how to retry when it cannot. Nothing is downloaded,
+and the network is not used, when every copy is present; unpinned names, local
+paths and bundled features are never touched. The plugin loader itself stays
+offline. The desktop app does the same when it opens a book.
+
+Once a package's pinned version is installed (by `ext add` or a restore), its
+other downloaded versions under `plugins/npm/<name>/` are deleted — a cache
+that a pulled pin or branch switch would otherwise leave to pile up — except a
+version another enabled manifest entry still pins. A failed install removes the
+folders it created and nothing else.
+
 ```sh
 gutterpress ext add <source> [dir] [options]
 
@@ -518,9 +549,10 @@ Order is load order: a later entry's markdown runs after earlier entries' (and s
 
 Pinned npm packages and their runtime dependencies live under `plugins/npm/`
 as a plain nested `node_modules` tree, which Node's own module resolution loads.
-They travel with the project and builds never fetch from the registry; each
-tarball's integrity is checked against the registry's hash when it is
-installed. Install/build scripts, native addon compilation, bundled
+The pin travels with the project; the downloaded copy is gitignored, and
+`build`, `validate`, `preflight` and `preview` download a missing pinned version first
+(nothing is fetched when every copy is present). Each tarball's integrity is
+checked against the registry's hash when it is installed. Install/build scripts, native addon compilation, bundled
 `node_modules`, and non-registry dependency selectors are intentionally
 unsupported. Only install packages you trust: extensions run unsandboxed with
 the process's full filesystem and network privileges.

package/dist/api/index.d.ts

@@ -21,7 +21,8 @@ export { getSystemDiagnostics, } from "../lib/diagnostics";
 export type { ToolStatus, SystemDiagnostics, } from "../lib/diagnostics";
 export { detectProjectSource, capabilitiesFor, findEnclosingRepoDir, repoSubPath, repoRootForSource, } from "../lib/project-source";
 export type { ProjectSource, ProjectCapabilities, } from "../lib/project-source";
-export { scaffoldProject, adoptFolder, ensureGitignoreHasDist, slugifyProjectName, escapeYamlScalar, } from "../lib/project-scaffold.ts";
+export { scaffoldProject, adoptFolder, slugifyProjectName, escapeYamlScalar, } from "../lib/project-scaffold.ts";
+export { ensureProjectGitignore } from "../lib/project-gitignore.ts";
 export type { ProjectTemplateId, ProjectVersionHistoryMode, CreateProjectOptions, CustomPageOptions, AdoptFolderOptions, CreateProjectResult, CreateProjectErrorCode, CreateProjectError, } from "../lib/project-scaffold.ts";
 export { scaffoldExtension, resolveExtensionPrefix, EXTENSION_KINDS, RESERVED_PREFIX, } from "../lib/extension-scaffold.ts";
 export type { ExtensionKind, ScaffoldExtensionOptions, ScaffoldExtensionResult, } from "../lib/extension-scaffold.ts";
@@ -37,6 +38,8 @@ export { listProjectExtensions, describeExtension, addExtension, checkExtensionU
 export type { ProjectExtensionEntry, ExtensionValidationResult, RecommendedExtension, ExtensionSourceKind, BuiltInStyleSet, BuiltInStyleSetId, AddExtensionOptions, ExtensionUpdateCheck, ExtensionUpdateResult, CheckExtensionUpdatesOptions, UpdateExtensionsOptions, } from "../lib/extension-manager.ts";
 export { BUNDLED_EXTENSIONS, isBundledExtension, isPathSpecifier, parseExtensionSpecifier, } from "../lib/extension-specifier.ts";
 export type { ParsedExtensionSpecifier } from "../lib/extension-specifier.ts";
+export { restorePinnedExtensions, restoreFailureMessage } from "../lib/extension-restore.ts";
+export type { RestorePinnedOptions, RestoreResult, RestoreFailure, RestoreProgress } from "../lib/extension-restore.ts";
 export { importExtensionFromFile, importExtensionFromUrl } from "../lib/extension-import.ts";
 export type { ExtensionImportResult, ExtensionImportWarning } from "../lib/extension-import.ts";
 export { MAX_SEARCH_BYTES, SEARCH_KEYWORDS, searchNpmExtensions, } from "../lib/extension-search.ts";

package/dist/api/index.js

@@ -46,7 +46,7 @@ import {
   describeExtension,
   diagnoseProjectRemote,
   disconnectPublishCredential,
-  ensureGitignoreHasDist,
+  ensureProjectGitignore,
   escapeYamlScalar,
   extensionCarries,
   extensionEntry,
@@ -106,6 +106,8 @@ import {
   resolveGoogleClientSecret,
   resolvePublishFormat,
   resolvePublishRequest,
+  restoreFailureMessage,
+  restorePinnedExtensions,
   revokeGoogleCredential,
   runBuild,
   runPublish,
@@ -129,7 +131,7 @@ import {
   testRemoteAccess,
   updateExtensions,
   validateProjectExtensions
-} from "../index-nk2mt7gp.js";
+} from "../index-ss8dv3zf.js";
 import {
   BuildError
 } from "../index-ee7wp8q3.js";
@@ -188,6 +190,8 @@ export {
   runBuild,
   revokeGoogleCredential,
   restoreVersionWithBackup,
+  restorePinnedExtensions,
+  restoreFailureMessage,
   resolvePublishRequest,
   resolvePublishFormat,
   resolveLogger,
@@ -255,7 +259,7 @@ export {
   extensionEntry,
   extensionCarries,
   escapeYamlScalar,
-  ensureGitignoreHasDist,
+  ensureProjectGitignore,
   disconnectPublishCredential,
   diagnoseProjectRemote,
   detectProjectSource,

package/dist/{build-ee2traqp.js → build-bk0rw638.js}

@@ -1,17 +1,17 @@
 import {
   runBuild,
   splitOutPath
-} from "./cli-4d4xegsw.js";
+} from "./cli-ac7zs8sp.js";
 import {
   log
-} from "./cli-6s4pkvbx.js";
+} from "./cli-n9e1mzb7.js";
 import {
   UsageError,
   parseFormat,
   parsePdfxFlavor,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-cg03zvez.js";
+} from "./cli-nzzsyw1e.js";
 import"./cli-wqy8hnnh.js";
 import {
   BuildError
@@ -53,15 +53,17 @@ var build_default = defineCommand({
       log.info(`Format: ${format}`);
       const pdfxFlavor = parsePdfxFlavor(args["pdfx-flavor"], format);
       const { outDir, pdfFileOverride } = splitOutPath(typeof args.out === "string" ? args.out : undefined, format);
+      const inputDir = path.resolve(args.input ?? ".");
+      const manifestPath = typeof args.manifest === "string" ? args.manifest : undefined;
       await runBuild({
-        inputDir: path.resolve(args.input ?? "."),
+        inputDir,
         format,
         outDir,
         pdfFileOverride,
         title: typeof args.title === "string" ? args.title : undefined,
         pdfxFlavor,
         iccPath: typeof args.icc === "string" ? args.icc : undefined,
-        manifestPath: typeof args.manifest === "string" ? args.manifest : undefined,
+        manifestPath,
         stripAnnotations: typeof args["strip-annotations"] === "boolean" ? args["strip-annotations"] : undefined,
         skipLint: !!args["skip-lint"],
         skipPreValidate: !!args["skip-pre-validate"],