codz-cli 0.0.0-stage → 0.1.0

package/dist/starters/registry.js

@@ -0,0 +1,258 @@
+// The catalog client: a signed index on a static host, public manifests,
+// free archives as public files and paid archives through a short-lived
+// download URL. Everything it returns has been checked against the signed
+// index; the engine only ever receives a VerifiedTemplate.
+//
+// The index is refused when its signature fails, when its sequence number is
+// lower than one this machine has seen (or equal with different contents), and
+// when it has expired, so a mirror cannot replay or freeze an old catalog to
+// hide a revocation. A revoked version is refused even from the cache.
+import { ToolError } from "../core/types.js";
+import { auth } from "./auth.js";
+import { readHomeFile, removeHome, writeHomeFile } from "./home.js";
+import { apiError, checkUrl, request } from "./http.js";
+import { compareVersions, ID_RE, parseManifest, VERSION_RE } from "./manifest.js";
+import { LIMITS } from "./paths.js";
+import { keyId, OFFICIAL_KEYS, sha256, verifySignature } from "./sign.js";
+import { fromArchive } from "./source.js";
+import { parseStrictJson } from "./strictJson.js";
+/** The official catalog. Empty until it is live; CODZ_REGISTRY points at another one (staging, tests). */
+export const OFFICIAL_REGISTRY = { base: '', api: '' };
+export function registryConfig() {
+    const env = process.env.CODZ_REGISTRY;
+    if (env) {
+        const keys = {};
+        for (const k of (process.env.CODZ_REGISTRY_KEYS ?? '').split(',').map((x) => x.trim()).filter(Boolean))
+            keys[keyId(k)] = k;
+        return { base: checkUrl(env, 'CODZ_REGISTRY'), api: checkUrl(process.env.CODZ_REGISTRY_API || env, 'CODZ_REGISTRY_API'), keys, official: false };
+    }
+    if (!OFFICIAL_REGISTRY.base)
+        throw new ToolError('catalog_unavailable', 'The starter catalog is not online yet.', 'Use a template folder: codz new <name> --template ./my-starter');
+    return { base: checkUrl(OFFICIAL_REGISTRY.base, 'registry'), api: checkUrl(OFFICIAL_REGISTRY.api || OFFICIAL_REGISTRY.base, 'registry API'), keys: OFFICIAL_KEYS, official: true };
+}
+const join = (base, path) => new URL(path.replace(/^\//, ''), base.href.endsWith('/') ? base : new URL(`${base.href}/`));
+const badIndex = (why) => new ToolError('bad_template', `The catalog index is not valid: ${why}.`, 'Try again later; report it if it persists.');
+export function parseIndex(text) {
+    const raw = parseStrictJson(text, 'the catalog index', { maxBytes: 8 * 1024 * 1024 });
+    if (!raw || typeof raw !== 'object' || raw.schema !== 1)
+        throw badIndex('unknown schema');
+    if (!Number.isInteger(raw.seq) || raw.seq < 0)
+        throw badIndex('bad sequence number');
+    if (Number.isNaN(Date.parse(raw.issued)) || Number.isNaN(Date.parse(raw.expires)))
+        throw badIndex('bad dates');
+    if (!Array.isArray(raw.templates) || !Array.isArray(raw.revoked))
+        throw badIndex('missing lists');
+    if (raw.timestampKeys !== undefined && (!Array.isArray(raw.timestampKeys) || raw.timestampKeys.length > 8 || !raw.timestampKeys.every((k) => typeof k === 'string' && /^[A-Za-z0-9+/]{43}=$/.test(k))))
+        throw badIndex('bad timestamp keys');
+    for (const t of raw.templates) {
+        if (!ID_RE.test(t?.id ?? '') || typeof t.title !== 'string' || !Array.isArray(t.versions) || !VERSION_RE.test(t.latest ?? ''))
+            throw badIndex(`a bad entry ${String(t?.id).slice(0, 40)}`);
+        if (t.tier !== 'free' && t.tier !== 'paid')
+            throw badIndex(`${t.id} has no price tier`);
+        for (const v of t.versions)
+            if (!VERSION_RE.test(v?.version ?? '') || !/^[0-9a-f]{64}$/.test(v.archive?.sha256 ?? '') || !/^[0-9a-f]{64}$/.test(v.manifest?.sha256 ?? ''))
+                throw badIndex(`${t.id} has a bad version entry`);
+    }
+    return raw;
+}
+export function parseTimestamp(text) {
+    const t = parseStrictJson(text, 'the catalog timestamp', { maxBytes: 16 * 1024 });
+    if (!t || t.schema !== 1 || !/^[0-9a-f]{64}$/.test(t.index_sha256 ?? '') || !Number.isInteger(t.seq) || Number.isNaN(Date.parse(t.issued)) || Number.isNaN(Date.parse(t.expires)))
+        throw badIndex('the timestamp file is not valid');
+    return t;
+}
+/** Checks timestamp.json against the index it must pin. Returns it, or throws index_expired / index_rollback. */
+function checkTimestamp(index, digest, tsBytes, tsSig, state) {
+    const keys = {};
+    for (const k of index.timestampKeys ?? [])
+        keys[keyId(k)] = k;
+    verifySignature(tsBytes, tsSig, keys, 'the catalog timestamp');
+    const ts = parseTimestamp(tsBytes.toString('utf8'));
+    if (ts.index_sha256 !== digest || ts.seq !== index.seq)
+        throw new ToolError('index_expired', 'The catalog\'s freshness note is for a different catalog, so it may be out of date.', 'Retry in a minute; report it if it persists.');
+    if (state?.tsIssued && Date.parse(ts.issued) < Date.parse(state.tsIssued) && state.sha256 === digest)
+        throw new ToolError('index_rollback', 'The catalog\'s freshness note is older than one this machine has already seen.', 'Retry later; report it if it persists. Nothing was downloaded.');
+    if (Date.parse(ts.expires) < Date.now())
+        throw new ToolError('index_expired', `The catalog has not been confirmed as current since ${ts.issued.slice(0, 16).replace('T', ' ')} UTC, so it may be hiding withdrawn versions.`, 'Retry later; report it if it persists.');
+    return ts;
+}
+function stored(cfg) {
+    const bytes = readHomeFile('starters', 'index.json');
+    const sig = readHomeFile('starters', 'index.json.sig');
+    const st = readHomeFile('starters', 'state.json');
+    if (!bytes || !sig || !st)
+        return null;
+    try {
+        const state = JSON.parse(st.toString('utf8'));
+        if (state.registry !== cfg.base.href)
+            return null;
+        return { bytes, sig, state };
+    }
+    catch {
+        return null;
+    }
+}
+export async function loadIndex(opts = {}) {
+    const cfg = registryConfig();
+    const warnings = cfg.official ? [] : [`Using the catalog at ${cfg.base.host} from CODZ_REGISTRY, not the official one.`];
+    const have = stored(cfg);
+    if (opts.cached) {
+        if (!have)
+            throw new ToolError('offline_not_cached', 'There is no downloaded catalog on this machine.', 'Run once online, or use a template folder.');
+        verifySignature(have.bytes, have.sig, cfg.keys, 'the catalog index');
+        const index = parseIndex(have.bytes.toString('utf8'));
+        let current = Date.parse(index.expires);
+        if (index.timestampKeys?.length) {
+            const tb = readHomeFile('starters', 'timestamp.json');
+            const tsig = readHomeFile('starters', 'timestamp.json.sig');
+            let ts = null;
+            try {
+                if (tb && tsig) {
+                    const keys = {};
+                    for (const k of index.timestampKeys)
+                        keys[keyId(k)] = k;
+                    verifySignature(tb, tsig, keys, 'the catalog timestamp');
+                    ts = parseTimestamp(tb.toString('utf8'));
+                }
+            }
+            catch {
+                ts = null;
+            }
+            current = Math.min(current, ts && ts.index_sha256 === sha256(have.bytes) ? Date.parse(ts.expires) : 0);
+        }
+        if (current < Date.now())
+            warnings.push('The downloaded catalog is no longer confirmed as current; withdrawals announced since then are not known on this machine.');
+        return { index, warnings, fromCache: true };
+    }
+    const r = await request(join(cfg.base, 'v1/index.json'), { etag: !opts.refresh ? have?.state.etag : undefined, maxBytes: 8 * 1024 * 1024 });
+    let bytes;
+    let sig;
+    if (r.status === 304 && have) {
+        bytes = have.bytes;
+        sig = have.sig;
+    }
+    else if (r.status === 200) {
+        bytes = r.body;
+        const s = await request(join(cfg.base, 'v1/index.json.sig'), { maxBytes: 16 * 1024 });
+        if (s.status !== 200)
+            throw apiError(s, { hadToken: false, what: 'the catalog signature' });
+        sig = s.body;
+    }
+    else
+        throw apiError(r, { hadToken: false, what: 'the catalog index' });
+    verifySignature(bytes, sig, cfg.keys, 'the catalog index');
+    const index = parseIndex(bytes.toString('utf8'));
+    const digest = sha256(bytes);
+    if (have) {
+        if (index.seq < have.state.seq || (index.seq === have.state.seq && digest !== have.state.sha256)) {
+            throw new ToolError('index_rollback', `The catalog (number ${index.seq}) is older than one this machine has already seen (number ${have.state.seq}).`, 'Retry later; report it if it persists. Nothing was downloaded.');
+        }
+    }
+    if (Date.parse(index.expires) < Date.now())
+        throw new ToolError('index_expired', `The catalog expired on ${index.expires.slice(0, 10)}, so it may be hiding withdrawn versions.`, 'Retry later; report it if it persists.');
+    // Two-key catalogs: the offline-signed index names online keys, and one of them confirms every few hours that this index is current.
+    let ts = null;
+    if (index.timestampKeys?.length) {
+        const t = await request(join(cfg.base, 'v1/timestamp.json'), { maxBytes: 16 * 1024 });
+        const ts2 = await request(join(cfg.base, 'v1/timestamp.json.sig'), { maxBytes: 16 * 1024 });
+        if (t.status !== 200 || ts2.status !== 200)
+            throw new ToolError('index_expired', 'The catalog\'s freshness note is missing, so it may be out of date.', 'Retry later; report it if it persists.');
+        ts = { bytes: t.body, sig: ts2.body, parsed: checkTimestamp(index, digest, t.body, ts2.body, have?.state) };
+    }
+    writeHomeFile(bytes, {}, 'starters', 'index.json');
+    writeHomeFile(sig, {}, 'starters', 'index.json.sig');
+    if (ts) {
+        writeHomeFile(ts.bytes, {}, 'starters', 'timestamp.json');
+        writeHomeFile(ts.sig, {}, 'starters', 'timestamp.json.sig');
+    }
+    writeHomeFile(JSON.stringify({ seq: index.seq, sha256: digest, etag: r.headers.get('etag') ?? undefined, registry: cfg.base.href, tsIssued: ts?.parsed.issued ?? (have?.state.sha256 === digest ? have?.state.tsIssued : undefined) }), {}, 'starters', 'state.json');
+    return { index, warnings, fromCache: false };
+}
+// ---------- Resolving and downloading ----------
+export function parseRef(ref) {
+    const [id, version] = ref.split('@');
+    if (!ID_RE.test(id ?? '') || (version !== undefined && !VERSION_RE.test(version)))
+        throw new ToolError('bad_args', `"${ref.slice(0, 80)}" is not a starter id (use id or id@x.y.z), or a folder.`, 'List starters with: codz starters list');
+    return { id, version };
+}
+export function resolveRef(index, ref) {
+    const { id, version } = parseRef(ref);
+    const t = index.templates.find((x) => x.id === id);
+    if (!t)
+        throw new ToolError('template_not_found', `No starter called ${id}.`, 'Check the id with codz starters list.');
+    const want = version ?? t.latest;
+    const v = t.versions.find((x) => x.version === want);
+    if (!v)
+        throw new ToolError('version_not_found', `No version ${want} of ${id}.`, `Versions: ${t.versions.map((x) => x.version).join(', ')}`);
+    const revoked = index.revoked.find((x) => x.id === id && x.version === want);
+    if (revoked)
+        throw new ToolError('template_revoked', `${id} ${want} was withdrawn${revoked.reason ? `: ${revoked.reason}` : ''}.`, revoked.use ? `Use ${id}@${revoked.use}.` : `Use a newer version (latest: ${t.latest}).`);
+    const warnings = [];
+    if (v.yanked)
+        warnings.push(`${id} ${want} was replaced by a newer version (latest: ${t.latest}).`);
+    if (v.needsUpdate)
+        warnings.push(`${id} ${want} is marked "needs update": it did not pass the latest SDK tests.`);
+    return { template: t, version: v, warnings };
+}
+export function latestUsable(t, index) {
+    const ok = t.versions.filter((v) => !v.yanked && !index.revoked.some((r) => r.id === t.id && r.version === v.version)).map((v) => v.version);
+    return ok.sort(compareVersions).pop() ?? t.latest;
+}
+/** The archive for one index entry, from the cache or the catalog, checked against the signed index. */
+export async function fetchTemplate(index, t, v, opts = {}) {
+    const cfg = registryConfig();
+    const cachePath = ['starters', 'cache', t.id, v.version, 'archive.tar.gz'];
+    let gz = readHomeFile(...cachePath);
+    let origin = 'cache';
+    if (gz && sha256(gz) !== v.archive.sha256) {
+        removeHome('starters', 'cache', t.id, v.version);
+        gz = null;
+        if (opts.cached)
+            throw new ToolError('checksum_mismatch', `The downloaded copy of ${t.id} ${v.version} does not match the catalog, so it was removed.`, 'Run again without --cached to download it again.');
+    }
+    if (!gz) {
+        if (opts.cached)
+            throw new ToolError('offline_not_cached', `${t.id} ${v.version} is not downloaded on this machine.`, 'Run once online, or use a template folder.');
+        let url;
+        let token;
+        if (t.tier === 'paid') {
+            // Downloading a paid starter uses the account's entitlement: only a person at a terminal starts that.
+            if (process.env.CODZ_MCP === '1')
+                throw new ToolError('needs_approval', `${t.id} is a paid starter and is not downloaded on this machine yet.`, `Ask the user to run codz new <name> --template ${t.id}@${v.version} in a terminal (or --dry-run to only download it); then it can be planned here.`);
+            token = await auth.accessToken();
+            if (!token)
+                throw new ToolError('not_logged_in', `${t.id} needs an account.`, 'Run codz login (or set CODZ_TOKEN in CI).');
+            const r = await request(join(cfg.api, 'v1/download-url'), { method: 'POST', json: { id: t.id, version: v.version }, token, maxBytes: 64 * 1024 });
+            if (r.status !== 200)
+                throw apiError(r, { hadToken: true, what: `${t.id} ${v.version}` });
+            const u = parseStrictJson(r.body.toString('utf8'), 'the download answer').url;
+            url = checkUrl(String(u ?? ''), 'the download URL');
+        }
+        else
+            url = join(cfg.base, `v1/templates/${t.id}/${v.version}/archive.tar.gz`);
+        const r = await request(url, { maxBytes: LIMITS.compressedBytes, timeoutMs: 120_000 });
+        if (r.status !== 200)
+            throw apiError(r, { hadToken: !!token, what: `${t.id} ${v.version}` });
+        gz = r.body;
+        if (sha256(gz) !== v.archive.sha256)
+            throw new ToolError('checksum_mismatch', `The download of ${t.id} ${v.version} does not match the signed catalog.`, 'Retry; if it persists, do not use the template and report it.');
+        writeHomeFile(gz, {}, ...cachePath);
+        origin = 'catalog';
+    }
+    const verified = fromArchive(gz, origin);
+    if (verified.manifest.id !== t.id || verified.manifest.version !== v.version)
+        throw new ToolError('bad_template', `The archive says it is ${verified.manifest.id} ${verified.manifest.version}, not ${t.id} ${v.version}.`, 'Do not use it; report it.');
+    if (sha256(verified.manifestBytes) !== v.manifest.sha256)
+        throw new ToolError('checksum_mismatch', `The manifest of ${t.id} ${v.version} does not match the signed catalog.`, 'Do not use it; report it.');
+    return verified;
+}
+/** A public manifest, checked against the signed index (for starters show). */
+export async function fetchManifest(t, v) {
+    const cfg = registryConfig();
+    const r = await request(join(cfg.base, `v1/templates/${t.id}/${v.version}/manifest.json`), { maxBytes: 4 * 1024 * 1024 });
+    if (r.status !== 200)
+        throw apiError(r, { hadToken: false, what: `${t.id} ${v.version}` });
+    if (sha256(r.body) !== v.manifest.sha256)
+        throw new ToolError('checksum_mismatch', `The manifest of ${t.id} ${v.version} does not match the signed catalog.`, 'Retry later; report it if it persists.');
+    return parseManifest(r.body.toString('utf8'));
+}

package/dist/starters/sign.js

@@ -0,0 +1,72 @@
+// Ed25519 signatures with Node's built-in crypto. A signature file sits next
+// to the signed file (index.json → index.json.sig) and signs its exact bytes,
+// never a re-serialised copy. It may hold several signatures, so a new key can
+// be added before an old one is retired.
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify } from 'node:crypto';
+import { ToolError } from "../core/types.js";
+import { parseStrictJson } from "./strictJson.js";
+/**
+ * Public keys this codz release trusts for the official catalog, by key id.
+ * Empty until the catalog is live; a registry set with CODZ_REGISTRY brings
+ * its own keys in CODZ_REGISTRY_KEYS.
+ */
+export const OFFICIAL_KEYS = {};
+const SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+export function publicKeyFromRaw(rawBase64) {
+    const raw = Buffer.from(rawBase64, 'base64');
+    if (raw.length !== 32)
+        throw new ToolError('signature_invalid', 'A trusted key is not a 32-byte Ed25519 public key.', 'Check CODZ_REGISTRY_KEYS.');
+    return createPublicKey({ key: Buffer.concat([SPKI_PREFIX, raw]), format: 'der', type: 'spki' });
+}
+export function keyId(rawBase64) {
+    return createHash('sha256').update(Buffer.from(rawBase64, 'base64')).digest('hex').slice(0, 16);
+}
+export function sha256(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+/** Throws signature_invalid unless at least one signature by a trusted key verifies over `data`. */
+export function verifySignature(data, sigFile, trusted, what) {
+    const fail = (why) => {
+        throw new ToolError('signature_invalid', `The signature of ${what} could not be verified (${why}).`, 'Update codz; if it persists, do not use the catalog and report it.');
+    };
+    if (!Object.keys(trusted).length)
+        fail('this codz trusts no catalog keys');
+    let parsed;
+    try {
+        parsed = parseStrictJson(sigFile.toString('utf8'), `${what} signature`, { maxBytes: 16 * 1024 });
+    }
+    catch {
+        return fail('the signature file is not valid');
+    }
+    const sigs = parsed?.signatures;
+    if (!Array.isArray(sigs) || !sigs.length || sigs.length > 8)
+        fail('no signatures');
+    for (const s of sigs) {
+        if (typeof s?.keyid !== 'string' || typeof s?.sig !== 'string')
+            continue;
+        const raw = trusted[s.keyid];
+        if (!raw)
+            continue;
+        const sig = Buffer.from(s.sig, 'base64');
+        if (sig.length !== 64)
+            continue;
+        if (verify(null, data, publicKeyFromRaw(raw), sig))
+            return s.keyid;
+    }
+    return fail('no signature from a trusted key matches');
+}
+// ---------- Publishing side (scripts/starters.ts and tests) ----------
+export function generateKeys() {
+    const { privateKey, publicKey } = generateKeyPairSync('ed25519');
+    const der = publicKey.export({ format: 'der', type: 'spki' });
+    const publicRaw = der.subarray(SPKI_PREFIX.length).toString('base64');
+    return { privatePem: privateKey.export({ format: 'pem', type: 'pkcs8' }).toString(), publicRaw, keyid: keyId(publicRaw) };
+}
+export function signBytes(data, privatePem) {
+    const key = createPrivateKey(privatePem);
+    const der = createPublicKey(key).export({ format: 'der', type: 'spki' });
+    return { keyid: keyId(der.subarray(SPKI_PREFIX.length).toString('base64')), sig: sign(null, data, key).toString('base64') };
+}
+export function signatureFile(data, privatePems) {
+    return Buffer.from(JSON.stringify({ signatures: privatePems.map((p) => signBytes(data, p)) }, null, 2) + '\n');
+}

package/dist/starters/source.js

@@ -0,0 +1,98 @@
+// A template source: the manifest, the license and the project files, read
+// from a folder or an archive and verified against the manifest's hashes.
+// The engine only ever sees a VerifiedTemplate, so a template from the
+// catalog, the cache or the user's own disk goes through the same checks.
+import { lstatSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ToolError } from "../core/types.js";
+import { parseManifest } from "./manifest.js";
+import { checkCollisions, checkRelPath, LIMITS } from "./paths.js";
+import { sha256 } from "./sign.js";
+import { readTarGz } from "./tar.js";
+/** Checks every listed file is present with the right size and hash, and nothing else is there. */
+export function verifyFiles(m, files) {
+    const listed = new Set(m.files.map((f) => f.path));
+    const extra = [...files.keys()].filter((p) => !listed.has(p));
+    if (extra.length)
+        throw new ToolError('checksum_mismatch', `The template has files its manifest does not list: ${extra.slice(0, 5).join(', ')}${extra.length > 5 ? ', ...' : ''}.`, 'Clear the cache with codz starters cache --clear and retry; report it if it persists.');
+    for (const f of m.files) {
+        const data = files.get(f.path);
+        if (!data)
+            throw new ToolError('checksum_mismatch', `The template is missing ${f.path}.`, 'Clear the cache with codz starters cache --clear and retry; report it if it persists.');
+        if (data.length !== f.size || sha256(data) !== f.sha256)
+            throw new ToolError('checksum_mismatch', `${f.path} does not match its hash in the manifest.`, 'Clear the cache with codz starters cache --clear and retry; report it if it persists.');
+    }
+}
+export function fromArchive(gz, origin) {
+    const { files: all } = readTarGz(gz);
+    const manifestBytes = all.get('manifest.json');
+    const license = all.get('LICENSE');
+    if (!manifestBytes)
+        throw new ToolError('bad_template', 'The archive has no manifest.json.', 'Report it; the template is not usable as published.');
+    if (!license)
+        throw new ToolError('bad_template', 'The archive has no LICENSE.', 'Report it; the template is not usable as published.');
+    const files = new Map();
+    for (const [p, data] of all) {
+        if (p === 'manifest.json' || p === 'LICENSE')
+            continue;
+        if (!p.startsWith('files/'))
+            throw new ToolError('archive_unsafe', `The archive has an entry outside files/: "${p.slice(0, 120)}". Nothing was written.`, 'Do not use this template; report it.');
+        files.set(p.slice('files/'.length), data);
+    }
+    const manifest = parseManifest(manifestBytes.toString('utf8'));
+    verifyFiles(manifest, files);
+    return { manifest, manifestBytes, license: license.toString('utf8'), files, origin, archiveSha256: sha256(gz) };
+}
+/** A template folder on disk: manifest.json, LICENSE and files/. Links and special files are refused. */
+export function fromFolder(dir) {
+    const read = (name) => {
+        try {
+            const st = lstatSync(join(dir, name));
+            if (!st.isFile())
+                throw new ToolError('archive_unsafe', `${name} in the template folder is not a regular file.`, 'Templates hold regular files only.');
+            return readFileSync(join(dir, name));
+        }
+        catch (e) {
+            if (e instanceof ToolError)
+                throw e;
+            throw new ToolError('template_not_found', `${join(dir, name)} was not found.`, 'A template folder has manifest.json, LICENSE and files/.');
+        }
+    };
+    const manifestBytes = read('manifest.json');
+    const license = read('LICENSE');
+    const files = new Map();
+    let total = 0;
+    const walkDir = (rel) => {
+        for (const name of readdirSync(join(dir, 'files', rel)).sort()) {
+            const p = rel ? `${rel}/${name}` : name;
+            checkRelPath(p, 'template folder');
+            const st = lstatSync(join(dir, 'files', p));
+            if (st.isSymbolicLink())
+                throw new ToolError('archive_unsafe', `The template folder has a link: files/${p}. Nothing was written.`, 'Templates hold regular files only.');
+            if (st.isDirectory())
+                walkDir(p);
+            else if (st.isFile()) {
+                if (files.size >= LIMITS.entries)
+                    throw new ToolError('archive_too_large', `The template folder has more than ${LIMITS.entries} files.`);
+                total += st.size;
+                if (total > LIMITS.expandedBytes)
+                    throw new ToolError('archive_too_large', 'The template folder is larger than the safety limit.');
+                files.set(p, readFileSync(join(dir, 'files', p)));
+            }
+            else
+                throw new ToolError('archive_unsafe', `The template folder has a special file: files/${p}.`, 'Templates hold regular files only.');
+        }
+    };
+    try {
+        if (!lstatSync(join(dir, 'files')).isDirectory())
+            throw new Error('not a folder');
+    }
+    catch {
+        throw new ToolError('bad_template', `${dir} has no files/ folder.`, 'A template folder has manifest.json, LICENSE and files/.');
+    }
+    walkDir('');
+    checkCollisions([...files.keys()], 'template folder');
+    const manifest = parseManifest(manifestBytes.toString('utf8'));
+    verifyFiles(manifest, files);
+    return { manifest, manifestBytes, license: license.toString('utf8'), files, origin: dir };
+}

package/dist/starters/strictJson.js

@@ -0,0 +1,148 @@
+// A strict JSON parser for data that comes from the network or a template:
+// duplicate keys, deep nesting and oversized strings are errors, not
+// "last one wins". JSON.parse silently keeps the last duplicate, which lets a
+// tampered manifest say one thing to one reader and another to the next.
+import { ToolError } from "../core/types.js";
+export function parseStrictJson(text, what, limits = {}) {
+    const maxDepth = limits.maxDepth ?? 32;
+    const maxString = limits.maxString ?? 64 * 1024;
+    const maxBytes = limits.maxBytes ?? 8 * 1024 * 1024;
+    if (text.length > maxBytes)
+        throw bad(`${what} is larger than ${maxBytes} bytes.`);
+    let i = 0;
+    const fail = (msg) => {
+        throw bad(`${what} is not valid JSON: ${msg} at offset ${i}.`);
+    };
+    const ws = () => {
+        while (i < text.length && (text[i] === ' ' || text[i] === '\n' || text[i] === '\r' || text[i] === '\t'))
+            i++;
+    };
+    const str = () => {
+        if (text[i] !== '"')
+            fail('expected a string');
+        i++;
+        let out = '';
+        for (;;) {
+            if (i >= text.length)
+                fail('unterminated string');
+            const c = text[i];
+            if (c === '"') {
+                i++;
+                break;
+            }
+            if (c < ' ')
+                fail('control character in a string');
+            if (c === '\\') {
+                const e = text[i + 1];
+                const map = { '"': '"', '\\': '\\', '/': '/', b: '\b', f: '\f', n: '\n', r: '\r', t: '\t' };
+                if (e in map) {
+                    out += map[e];
+                    i += 2;
+                }
+                else if (e === 'u') {
+                    const hex = text.slice(i + 2, i + 6);
+                    if (!/^[0-9a-fA-F]{4}$/.test(hex))
+                        fail('bad \\u escape');
+                    out += String.fromCharCode(parseInt(hex, 16));
+                    i += 6;
+                }
+                else
+                    fail('bad escape');
+            }
+            else {
+                out += c;
+                i++;
+            }
+            if (out.length > maxString)
+                fail(`a string longer than ${maxString} characters`);
+        }
+        return out;
+    };
+    const value = (depth) => {
+        if (depth > maxDepth)
+            fail(`nesting deeper than ${maxDepth}`);
+        ws();
+        const c = text[i];
+        if (c === '{') {
+            i++;
+            const obj = Object.create(null);
+            ws();
+            if (text[i] === '}') {
+                i++;
+                return obj;
+            }
+            for (;;) {
+                ws();
+                const key = str();
+                if (Object.prototype.hasOwnProperty.call(obj, key))
+                    fail(`duplicate key "${key}"`);
+                ws();
+                if (text[i] !== ':')
+                    fail('expected ":"');
+                i++;
+                obj[key] = value(depth + 1);
+                ws();
+                if (text[i] === ',') {
+                    i++;
+                    continue;
+                }
+                if (text[i] === '}') {
+                    i++;
+                    return obj;
+                }
+                fail('expected "," or "}"');
+            }
+        }
+        if (c === '[') {
+            i++;
+            const arr = [];
+            ws();
+            if (text[i] === ']') {
+                i++;
+                return arr;
+            }
+            for (;;) {
+                arr.push(value(depth + 1));
+                ws();
+                if (text[i] === ',') {
+                    i++;
+                    continue;
+                }
+                if (text[i] === ']') {
+                    i++;
+                    return arr;
+                }
+                fail('expected "," or "]"');
+            }
+        }
+        if (c === '"')
+            return str();
+        if (text.startsWith('true', i))
+            return (i += 4), true;
+        if (text.startsWith('false', i))
+            return (i += 5), false;
+        if (text.startsWith('null', i))
+            return (i += 4), null;
+        const m = /^-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?/.exec(text.slice(i, i + 40));
+        if (!m)
+            fail('unexpected character');
+        i += m[0].length;
+        return Number(m[0]);
+    };
+    // A BOM is tolerated; nothing else before or after the value.
+    if (text.charCodeAt(0) === 0xfeff)
+        i = 1;
+    const v = value(0);
+    ws();
+    if (i !== text.length)
+        fail('extra text after the value');
+    return v;
+}
+function bad(message) {
+    return new ToolError('bad_template', message, 'Report it; this file is not usable as published.');
+}
+/** Strips control and escape characters from text shown in the terminal. */
+export function printable(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f​-‏‪-‮⁦-⁩]/g, '');
+}