@markii/pack 0.10.0 → 0.12.0

package/dist/archive.d.ts

@@ -0,0 +1,81 @@
+import type { PackManifest } from './manifest.js';
+/** Options bounding how much a single `.mkp` open is willing to materialize. Defaults match `@markii/bundle`'s own zip-bomb guard, since a pack archive is bounded the same way a bundle is. */
+export interface OpenPackArchiveOptions {
+    maxEntryBytes?: number;
+    maxTotalBytes?: number;
+}
+/**
+ * Why an `openPackArchive` call failed. `kind: 'zip'` covers everything
+ * `openZipBundle` itself rejects (a path-escaping entry, an oversized
+ * entry, a corrupt or malformed zip, ZIP64, a CRC mismatch, a name
+ * collision) — the message is already loud and specific, so it is passed
+ * through rather than re-summarized. `kind: 'manifest'` covers a
+ * `pack.json` that parses to invalid JSON or fails `parsePackManifest`.
+ * `kind: 'missing-entry'` covers a `.mkp` that lacks a required root entry.
+ */
+export type PackArchiveError = {
+    kind: 'zip';
+    message: string;
+} | {
+    kind: 'manifest';
+    errors: string[];
+} | {
+    kind: 'missing-entry';
+    entry: string;
+    message: string;
+};
+export type OpenPackArchiveResult = {
+    ok: true;
+    archive: PackArchiveContents;
+} | {
+    ok: false;
+    error: PackArchiveError;
+};
+/** The validated, read-only contents of a `.mkp` archive. */
+export interface PackArchiveContents {
+    /** The parsed, validated `pack.json`. */
+    readonly manifest: PackManifest;
+    /** Forward-compatible warnings from parsing `pack.json` (unknown keys etc.) — see `parsePackManifest`. */
+    readonly manifestWarnings: readonly string[];
+    /** The prebuilt registration script's bytes (`webview.js`, always present — see this module's doc comment). */
+    readonly scriptBytes: Uint8Array;
+    /** The prebuilt stylesheet's bytes (`webview.css`), present only when the pack ships one. */
+    readonly stylesheetBytes?: Uint8Array;
+    /** Shared Lua modules under `scripts/`, keyed by their path relative to that folder (e.g. `"http.lua"` for `scripts/http.lua`). Empty when the pack ships none. */
+    readonly scriptModules: Readonly<Record<string, Uint8Array>>;
+    /**
+     * Archive-root entries present in the zip but outside the prebuilt
+     * contract (e.g. a leftover component source alongside the compiled
+     * script, or an entry nested under a subfolder rather than at the zip
+     * root). Never an error: `.mkp` follows the same "prebuilt wins,
+     * anything else is ignored" posture a pack folder already has for a
+     * `webview.js` sitting beside sources. A host's diagnostics surface may
+     * report these; this module only supplies the facts.
+     */
+    readonly ignoredEntries: readonly string[];
+}
+/**
+ * Opens a `.mkp` archive from its raw bytes and validates it against the
+ * prebuilt-pack contract. Never throws: every failure — a hostile or
+ * corrupt zip, a missing required entry, an invalid `pack.json` — comes
+ * back as `{ ok: false, error }` rather than an exception, so a caller can
+ * report the reason without a `try`/`catch` of its own.
+ */
+export declare function openPackArchive(bytes: Uint8Array, options?: OpenPackArchiveOptions): Promise<OpenPackArchiveResult>;
+/**
+ * The archive naming rule for a PRODUCED `.mkp`: `<name>-<version>.mkp`
+ * when `pack.json` declares a `version`, or `<name>.mkp` when it does not.
+ *
+ * `version` is optional in the manifest (see `PackManifest`'s doc comment)
+ * and its absence is valid, not an error — so a produced archive's name
+ * must stay valid too. Falling back to the bare pack name rather than
+ * inventing a placeholder version (`0.0.0`, `unversioned`, ...) avoids
+ * claiming a version the manifest never declared: the filename says exactly
+ * as much as the manifest does, no more.
+ *
+ * Both `name` and a present `version` are already validated by
+ * `parsePackManifest` (lowercase-kebab; plain `MAJOR.MINOR.PATCH` digits
+ * and dots) before this function ever sees them, so no further escaping is
+ * needed to use them as a filename.
+ */
+export declare function packArchiveFileName(manifest: Pick<PackManifest, 'name' | 'version'>): string;

package/dist/archive.js

@@ -0,0 +1,200 @@
+/**
+ * `.mkp` pack archives (docs/packs.md, issue #16): a zip of a pack's
+ * PREBUILT form, files at the zip root — `pack.json`, `webview.js`,
+ * `webview.css` when the pack has styles, `scripts/` when the pack ships
+ * shared Lua. This is the reader half: given the raw bytes of a `.mkp`
+ * file, validate it and expose its contents for read-only loading.
+ *
+ * A `.mkp` is prebuilt-only, on purpose (docs/packs.md's "Two ways to run a
+ * pack: prebuilt and from source"): this module never compiles anything. A
+ * `webview.js` at the archive root is REQUIRED — an archive that ships only
+ * component sources is not a valid `.mkp`, because there would be nothing
+ * for a host to load without running a compiler, and `.mkp` exists
+ * precisely for hosts that may not carry one.
+ *
+ * This reader reuses `@markii/bundle`'s zip reader (`openZipBundle`)
+ * rather than re-implementing zip parsing or a path jail: AGENTS.md calls a
+ * reimplemented jail a bug. `openZipBundle` already rejects a `../`
+ * segment, an absolute path, a backslash path, or a Windows drive-letter
+ * path in any entry name (zip-slip), and bounds both a single entry's and
+ * the whole archive's declared uncompressed size before any bytes are
+ * inflated (the zip-bomb guard) — see `packages/markii-bundle/src/zip.ts`.
+ * Reusing it means a `.mkp` gets the exact same `bounded-open` guarantee a
+ * `.mkz` bundle gets, with no second implementation to drift out of sync.
+ *
+ * This module never touches a real filesystem: it takes bytes in and
+ * returns parsed, in-memory contents (or a structured error) out. It never
+ * writes anything anywhere, so "nothing is written outside the pack
+ * directory" holds structurally for every rejection path — there is no
+ * write side to leak from. A host that wants to install a `.mkp` (unzip it
+ * into its own pack directory) is a separate, host-specific concern (the
+ * brief's "Install pack from file" command) and is out of this module's
+ * scope entirely.
+ */
+import { BundleZipError, DEFAULT_MAX_ZIP_ENTRY_BYTES, DEFAULT_MAX_ZIP_TOTAL_BYTES, openZipBundle, } from '@markii/bundle';
+import { parsePackManifest } from './manifest.js';
+/** The archive-root entry names the prebuilt contract reserves. */
+const MANIFEST_ENTRY = 'pack.json';
+const SCRIPT_ENTRY = 'webview.js';
+const STYLESHEET_ENTRY = 'webview.css';
+const SCRIPTS_DIR_PREFIX = 'scripts/';
+function isScriptModulePath(path) {
+    return (path.startsWith(SCRIPTS_DIR_PREFIX) &&
+        path.length > SCRIPTS_DIR_PREFIX.length);
+}
+/**
+ * Decodes UTF-8 bytes, rejecting anything that is not well-formed UTF-8
+ * rather than silently substituting replacement characters (the default
+ * `TextDecoder` behavior) — a `pack.json` that decodes to mangled text
+ * should fail loudly as a manifest problem, not parse whatever garbled JSON
+ * `�` substitution happens to produce.
+ */
+function decodeUtf8Strict(bytes) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Opens a `.mkp` archive from its raw bytes and validates it against the
+ * prebuilt-pack contract. Never throws: every failure — a hostile or
+ * corrupt zip, a missing required entry, an invalid `pack.json` — comes
+ * back as `{ ok: false, error }` rather than an exception, so a caller can
+ * report the reason without a `try`/`catch` of its own.
+ */
+export async function openPackArchive(bytes, options = {}) {
+    const maxEntryBytes = options.maxEntryBytes ?? DEFAULT_MAX_ZIP_ENTRY_BYTES;
+    const maxTotalBytes = options.maxTotalBytes ?? DEFAULT_MAX_ZIP_TOTAL_BYTES;
+    let storage;
+    try {
+        storage = openZipBundle(bytes, { maxEntryBytes, maxTotalBytes });
+    }
+    catch (err) {
+        if (err instanceof BundleZipError) {
+            return { ok: false, error: { kind: 'zip', message: err.message } };
+        }
+        return {
+            ok: false,
+            error: {
+                kind: 'zip',
+                message: `pack archive rejected: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        };
+    }
+    const paths = await storage.list();
+    if (!paths.includes(MANIFEST_ENTRY)) {
+        return {
+            ok: false,
+            error: {
+                kind: 'missing-entry',
+                entry: MANIFEST_ENTRY,
+                message: `pack archive rejected: no "${MANIFEST_ENTRY}" entry at the archive root`,
+            },
+        };
+    }
+    if (!paths.includes(SCRIPT_ENTRY)) {
+        return {
+            ok: false,
+            error: {
+                kind: 'missing-entry',
+                entry: SCRIPT_ENTRY,
+                message: `pack archive rejected: no "${SCRIPT_ENTRY}" entry at the archive root: a .mkp carries a pack's prebuilt form only, never its sources, so a compiled ${SCRIPT_ENTRY} is required`,
+            },
+        };
+    }
+    const manifestBytes = await storage.read(MANIFEST_ENTRY);
+    // Not reachable in practice (the entry was just confirmed present in the
+    // same storage instance's own listing), but `read` is typed to return
+    // `undefined` and this keeps the function honestly total rather than
+    // asserting past the type.
+    if (manifestBytes === undefined) {
+        return {
+            ok: false,
+            error: {
+                kind: 'missing-entry',
+                entry: MANIFEST_ENTRY,
+                message: `pack archive rejected: "${MANIFEST_ENTRY}" could not be read`,
+            },
+        };
+    }
+    const manifestText = decodeUtf8Strict(manifestBytes);
+    if (manifestText === undefined) {
+        return {
+            ok: false,
+            error: {
+                kind: 'manifest',
+                errors: [`"${MANIFEST_ENTRY}" is not valid UTF-8`],
+            },
+        };
+    }
+    const parsed = parsePackManifest(manifestText);
+    if (!parsed.ok) {
+        return { ok: false, error: { kind: 'manifest', errors: parsed.errors } };
+    }
+    const scriptBytes = await storage.read(SCRIPT_ENTRY);
+    if (scriptBytes === undefined) {
+        return {
+            ok: false,
+            error: {
+                kind: 'missing-entry',
+                entry: SCRIPT_ENTRY,
+                message: `pack archive rejected: "${SCRIPT_ENTRY}" could not be read`,
+            },
+        };
+    }
+    let stylesheetBytes;
+    if (paths.includes(STYLESHEET_ENTRY)) {
+        stylesheetBytes = await storage.read(STYLESHEET_ENTRY);
+    }
+    const scriptModules = Object.create(null);
+    const ignoredEntries = [];
+    for (const path of paths) {
+        if (path === MANIFEST_ENTRY ||
+            path === SCRIPT_ENTRY ||
+            path === STYLESHEET_ENTRY) {
+            continue;
+        }
+        if (isScriptModulePath(path)) {
+            const data = await storage.read(path);
+            if (data !== undefined) {
+                scriptModules[path.slice(SCRIPTS_DIR_PREFIX.length)] = data;
+            }
+            continue;
+        }
+        ignoredEntries.push(path);
+    }
+    return {
+        ok: true,
+        archive: {
+            manifest: parsed.manifest,
+            manifestWarnings: parsed.warnings,
+            scriptBytes,
+            ...(stylesheetBytes !== undefined ? { stylesheetBytes } : {}),
+            scriptModules,
+            ignoredEntries,
+        },
+    };
+}
+/**
+ * The archive naming rule for a PRODUCED `.mkp`: `<name>-<version>.mkp`
+ * when `pack.json` declares a `version`, or `<name>.mkp` when it does not.
+ *
+ * `version` is optional in the manifest (see `PackManifest`'s doc comment)
+ * and its absence is valid, not an error — so a produced archive's name
+ * must stay valid too. Falling back to the bare pack name rather than
+ * inventing a placeholder version (`0.0.0`, `unversioned`, ...) avoids
+ * claiming a version the manifest never declared: the filename says exactly
+ * as much as the manifest does, no more.
+ *
+ * Both `name` and a present `version` are already validated by
+ * `parsePackManifest` (lowercase-kebab; plain `MAJOR.MINOR.PATCH` digits
+ * and dots) before this function ever sees them, so no further escaping is
+ * needed to use them as a filename.
+ */
+export function packArchiveFileName(manifest) {
+    return manifest.version === undefined
+        ? `${manifest.name}.mkp`
+        : `${manifest.name}-${manifest.version}.mkp`;
+}

package/dist/components.d.ts

@@ -2,9 +2,13 @@ import type { PackManifest } from './manifest.js';
 /**
  * Which directive form a pack component is written as. Mirrors
  * `@markii/stdlib`'s `ComponentKind`; defined locally here rather than
- * imported because `@markii/pack` is a published, zero-dependency package
- * (see AGENTS.md's Stack section) and `@markii/stdlib` is a sibling
- * package, not a dependency of this one. The two unions must stay aligned;
+ * imported because `@markii/stdlib` is a sibling package this package
+ * deliberately does not depend on, to stay decoupled from the reference
+ * renderer's component contracts (see AGENTS.md's Stack section). This is
+ * unrelated to `@markii/pack`'s dependency on `@markii/bundle` for `.mkp`
+ * archive reading (`./archive.ts`, issue #16): that dependency reuses a
+ * neutral, framework-agnostic zip reader and path jail, not a renderer
+ * contract. The two unions must stay aligned;
  * `@markii/host` (which depends on both) carries an executable check of
  * that alignment, since this package cannot import `@markii/stdlib` to
  * check it itself.

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export type { PackManifest, PackManifestParseResult } from './manifest.js';
 export { parsePackManifest } from './manifest.js';
+export type { OpenPackArchiveOptions, OpenPackArchiveResult, PackArchiveContents, PackArchiveError, } from './archive.js';
+export { openPackArchive, packArchiveFileName } from './archive.js';
 export type { PackComponentAttribute, PackComponentDefinition, PackComponentEntry, PackComponentKind, PackComponentListing, ResolvedPackComponent, } from './components.js';
 export { PACK_ATTRIBUTE_NAME_PATTERN, PACK_COMPONENT_KINDS, isPackAttributeName, packComponents, resolvePackComponent, } from './components.js';
 export type { ComposeDirectiveNameResult, NamespaceCollision, NamespaceValidationResult, } from './namespace.js';

package/dist/index.js

@@ -1,8 +1,12 @@
 // @markii/pack: the neutral component-pack contract (docs/packs.md). This
-// is slice 0 of issue #3 — the manifest shape, namespace/engine rules, and
-// hand-rolled validation only. No registry loading, no `uses:` surfacing,
-// no sandboxed `require`, no filesystem reads: those are later slices.
+// started as slice 0 of issue #3 — the manifest shape, namespace/engine
+// rules, and hand-rolled validation only, with no registry loading, no
+// `uses:` surfacing, no sandboxed `require`, and no filesystem reads. Issue
+// #16's `.mkp` archive reader (`./archive.ts`) is the first filesystem-
+// adjacent slice: it reads validated bytes in and returns parsed contents
+// out, touching no real filesystem itself (a host does that).
 export { parsePackManifest } from './manifest.js';
+export { openPackArchive, packArchiveFileName } from './archive.js';
 export { PACK_ATTRIBUTE_NAME_PATTERN, PACK_COMPONENT_KINDS, isPackAttributeName, packComponents, resolvePackComponent, } from './components.js';
 export { RESERVED_NAMESPACE_SEGMENTS, composeDirectiveName, detectNamespaceCollisions, validateLocalComponentName, validatePackName, } from './namespace.js';
 export { isValidPackNameShape, resolveUses } from './uses.js';

package/dist/manifest.d.ts

@@ -14,12 +14,31 @@ import type { PackComponentEntry } from './components.js';
  * `kind`/`attributes` metadata (see `./components.ts`,
  * `resolvePackComponent`, `packComponents`).
  *
+ * `components` may be an EMPTY object. There is exactly one way to share
+ * Lua beyond a bundle's own `scripts/` folder: a pack module. A folder of
+ * shared Lua with nothing to render is simply a pack whose `components`
+ * is `{}` and which carries its own `scripts/*.lua` — it contributes zero
+ * directives and never appears in a component catalog, but its modules
+ * still resolve through `require "name/module"` like any other pack's.
+ *
  * Shared Lua modules are NOT a manifest field. docs/packs.md says they
  * travel under a conventional `scripts/` directory inside the pack
  * (`require "ana/http"`), the same way a bundle's `scripts/` works — there
  * is no separate manifest declaration for them, so this type doesn't add
- * one. (Flagged in the slice-0 report for orchestrator sign-off in case
- * docs/packs.md meant something more explicit.)
+ * one.
+ *
+ * `version` is an OPTIONAL fourth field: a plain semver string
+ * (`MAJOR.MINOR.PATCH`, digits only, no leading zeros on a multi-digit
+ * component — see `SEMVER_PATTERN`). A pack that omits it keeps loading
+ * exactly as before, with no warning. Prerelease/build suffixes
+ * (`-beta.1`, `+build5`) are deliberately NOT accepted: AGENTS.md already
+ * commits this project to "plain semver" for spec versioning, and a pack
+ * version exists so a host can compare/display it, not to drive a resolver
+ * that needs prerelease ordering. Accepting a wider grammar than the one
+ * fact this field is for would be a casual-user-facing complication with
+ * no present consumer. A malformed `version` is an ERROR, not a
+ * forward-compatible warning, the same posture `name` gets: a version a
+ * host cannot trust is worse than no version.
  */
 export interface PackManifest {
     /** The pack's namespace, e.g. `"ana"`. See `validatePackName`. */
@@ -35,6 +54,12 @@ export interface PackManifest {
      * the one place both forms are normalized.
      */
     components: Record<string, PackComponentEntry>;
+    /**
+     * Optional plain-semver version string, e.g. `"1.0.0"`. Absent unless
+     * the pack author declared one. See this interface's doc comment for
+     * the accepted grammar and why prerelease/build suffixes are rejected.
+     */
+    version?: string;
 }
 export type PackManifestParseResult = {
     ok: true;

package/dist/manifest.js

@@ -1,6 +1,16 @@
 import { validateLocalComponentName, validatePackName } from './namespace.js';
 import { PACK_ATTRIBUTE_NAME_PATTERN, PACK_COMPONENT_KINDS, isPackAttributeName, } from './components.js';
-const KNOWN_TOP_LEVEL_KEYS = new Set(['name', 'engine', 'components']);
+const KNOWN_TOP_LEVEL_KEYS = new Set([
+    'name',
+    'engine',
+    'components',
+    'version',
+]);
+// Plain semver only: MAJOR.MINOR.PATCH, digits only, no leading zeros on a
+// multi-digit component ("1.0.0" and "0.0.1" are valid; "01.0.0" is not).
+// No prerelease or build metadata suffix — see PackManifest's doc comment
+// for why this field deliberately does not accept the wider semver grammar.
+const SEMVER_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
 // The keys a component's object-form entry may carry, and which of those
 // are required. Mirrors KNOWN_TOP_LEVEL_KEYS's role for the manifest root:
 // an unrecognized key here is a forward-compatible warning, not an error.
@@ -324,14 +334,28 @@ export function parsePackManifest(json) {
                 sanitized.attributes = attributes;
             result[key] = sanitized;
         }
-        if (Object.keys(componentsObj).length === 0) {
-            errors.push('"components" must have at least one entry');
-            componentsValid = false;
-        }
         if (componentsValid) {
             components = result;
         }
     }
+    // --- version (optional) ---
+    //
+    // Absent is valid and produces neither an error nor a warning. Present
+    // but malformed is an ERROR (rejects the whole manifest), not a
+    // forward-compatible warning: a version a host cannot trust is worse
+    // than no version at all, the same posture as a malformed `name`.
+    let version;
+    let versionValid = true;
+    if (Object.hasOwn(obj, 'version')) {
+        const rawVersion = obj.version;
+        if (typeof rawVersion !== 'string' || !SEMVER_PATTERN.test(rawVersion)) {
+            errors.push('"version" must be a plain semver string ("MAJOR.MINOR.PATCH", digits only, no leading zeros, no prerelease or build suffix)');
+            versionValid = false;
+        }
+        else {
+            version = rawVersion;
+        }
+    }
     // --- unknown top-level keys: forward-compat warning, not an error ---
     for (const key of Object.keys(obj)) {
         if (Object.hasOwn(obj, key) && !KNOWN_TOP_LEVEL_KEYS.has(key)) {
@@ -341,12 +365,15 @@ export function parsePackManifest(json) {
     if (errors.length > 0 ||
         name === undefined ||
         engine === undefined ||
-        components === undefined) {
+        components === undefined ||
+        !versionValid) {
         return { ok: false, errors };
     }
     return {
         ok: true,
-        manifest: { name, engine, components },
+        manifest: version === undefined
+            ? { name, engine, components }
+            : { name, engine, components, version },
         warnings,
     };
 }

package/dist/namespace.d.ts

@@ -92,9 +92,10 @@ export interface NamespaceCollision {
 /**
  * Given several installed pack namespaces, returns the ones that appear
  * more than once. Pure predicate only — docs/packs.md says installing two
- * packs with the same namespace is rejected at install time, but that
- * install-time rejection (and the vault-library-shadows-a-pack warning
- * case) is a later slice; this is the detection primitive it will use.
+ * packs with the same namespace is rejected at install time; `@markii/host`'s
+ * `discoverPacks` (`packages/markii-host/src/packs/discover.ts`) is the
+ * caller that applies this at install time, excluding every pack sharing a
+ * colliding namespace.
  *
  * Comparison is exact-string (case-sensitive), matching `validatePackName`
  * which already forces lowercase, so two namespaces differing only in case

package/dist/namespace.js

@@ -172,9 +172,10 @@ export function composeDirectiveName(packName, localName) {
 /**
  * Given several installed pack namespaces, returns the ones that appear
  * more than once. Pure predicate only — docs/packs.md says installing two
- * packs with the same namespace is rejected at install time, but that
- * install-time rejection (and the vault-library-shadows-a-pack warning
- * case) is a later slice; this is the detection primitive it will use.
+ * packs with the same namespace is rejected at install time; `@markii/host`'s
+ * `discoverPacks` (`packages/markii-host/src/packs/discover.ts`) is the
+ * caller that applies this at install time, excluding every pack sharing a
+ * colliding namespace.
  *
  * Comparison is exact-string (case-sensitive), matching `validatePackName`
  * which already forces lowercase, so two namespaces differing only in case

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@markii/pack",
-  "version": "0.10.0",
-  "description": "Component pack contract for Markii (docs/packs.md): the pack.json manifest shape, namespace and engine rules, and hand-rolled validation. No React, no parsing, no bundle loading.",
+  "version": "0.12.0",
+  "description": "Component pack contract for Markii (docs/packs.md): the pack.json manifest shape, namespace and engine rules, hand-rolled validation, and the .mkp prebuilt-archive reader. No React, no parsing.",
   "keywords": [
     "markdown",
     "mark",
@@ -40,5 +40,8 @@
     "build": "tsc --noEmit -p tsconfig.json",
     "build:dist": "rm -rf dist && tsc -p tsconfig.build.json",
     "lint": "eslint ."
+  },
+  "dependencies": {
+    "@markii/bundle": "0.12.0"
   }
 }